---
name: resolve-todos
description: Check a document for TODO items and resolve them. If a TODO has a clear instruction, complete it. If the instruction is unclear or missing, ask the user. Use when the user asks to "check for TODOs", "resolve TODOs", "find TODO items", or "complete the TODOs in this document".
---

# Resolve TODOs skill

## Purpose

Find all TODO items in a document, resolve the ones with clear instructions, and ask the user about any that are unclear or have no instruction.

## Trigger phrases

Use this skill when the user says things like:
- "check for TODOs in this document"
- "resolve the TODOs"
- "find TODO items"
- "complete the TODOs"
- "are there any TODOs?"

## How to run this skill

### Step 1 — Identify the target document

If the user named a specific file, use that. If not, check if a file is open in the IDE (visible via ide_opened_file context). If neither, ask: "Which document should I check for TODOs?"

### Step 2 — Read the document

Read the full document. Do not skim.

### Step 3 — Find all TODOs

Scan for TODO items in any of these forms:

- `TODO: some instruction` — inline in prose
- `TODO` — standalone, no instruction
- `<!-- TODO: some instruction -->` — HTML comment
- `[TODO: some instruction]` — bracket form
- `[TODO]` — bracket form, no instruction
- `**TODO:** some instruction` — bold markdown
- Any other variation where the word TODO appears, in any case (todo, Todo, TODO)

For each TODO found, record:
- Its location (line or section heading it appears under)
- The instruction text, if any
- Whether the instruction is clear enough to act on

### Step 4 — Classify each TODO

For each TODO, decide:

**Clear** — the instruction is specific enough to act on without asking. Examples:
- `TODO: add owner name` — clear, insert the owner name
- `TODO: replace with actual due date` — clear, flag that the date is missing and prompt user
- `TODO: expand this section with discovery findings` — clear intent, can draft or ask for the content

**Unclear** — the instruction is vague, contradictory, or missing. Examples:
- `TODO` — no instruction at all
- `TODO: fix this` — too vague to act on
- `TODO: update` — no indication of what to update

### Step 5 — Process clear TODOs

For each clear TODO, complete it directly:

- If the TODO requires inserting known information (a date, a name, a value already mentioned elsewhere in the document or conversation), insert it and remove the TODO marker.
- If the TODO requires drafting content (a paragraph, a section), draft it in place and remove the TODO marker.
- If the TODO requires information you do not have, note it as a question for Step 6 rather than guessing.

Apply all clear TODO resolutions as edits to the file. Do not ask for permission before editing — the user has already asked you to resolve them.

### Step 6 — Ask about unclear TODOs

For each unclear TODO (unclear instruction or no instruction), ask the user one at a time:

"I found a TODO at [location]: `[TODO text]`. What would you like me to do here?"

Wait for the answer. Apply it. Then move to the next unclear TODO.

Do not batch unclear TODOs into a list and ask all at once — work through them one by one so each answer can inform the next.

### Step 7 — Report

When all TODOs are resolved, tell the user:

- How many TODOs were found
- How many were resolved automatically
- How many required input (and confirm they are now resolved)
- If none were found, say so clearly: "No TODO items found in [filename]."

## Writing style

Follow the project writing style from CLAUDE.md:
- British English spelling
- Sentence case headings
- No banned vocabulary
- No em dashes - use hyphens
- Match the tone and style of the surrounding document when drafting content to fill TODOs

## Edge cases

- If a TODO marker appears inside a code block (fenced with ``` or indented), skip it — it is likely example code, not an actual task.
- If the same TODO text appears multiple times, treat each occurrence as a separate item.
- If completing one TODO makes another TODO redundant (e.g., filling in a name that was TODO'd in two places), resolve both in the same edit.