TODO Breakdown — Recursive Task Decomposition

File Status

TODO_N.md files have a Status in their header:

• Status: active — Currently being worked on. The traversal algorithm starts here.
• Status: planned — Pre-planned breakdown for future work. May need revision when activated.

When a planned file becomes the next to work on, the executor must verify the breakdown against the current codebase before executing (see Execution Protocol).

Execution order: Post-order DFS within each file — deepest leaves first, then parents marked complete, bubbling up to root.

Tree Links

Every node except the root needs a parent pointer. Every non-leaf needs child pointers. Without these, completion propagation breaks.

Parent pointer (in child file): **Parent:** 2.4 Child pointer (in parent file): **Children:** TODO_3 items 3.1, 3.2 File header: Parent: TODO_{N}.md + Decomposes: 2.4 → (3.1, 3.2)

Completion Marking

Prepend [DONE] to the item heading:

## [DONE] 3.1 — UserService.Create Happy Path Tests

Use the Edit tool to prepend [DONE] to the ## heading. Do not rewrite the rest of the item.

Deferred Items

Items explicitly marked as deferred (e.g., "Deferred to Phase 2") are NOT incomplete — they are intentionally out-of-scope for the current decomposition. Deferred items:

• Do NOT block parent completion
• Do NOT need [DONE] prefix (they were never in-scope)
• Are noted in the parent TODO.md for future planning

When checking "are all children done?", skip deferred items.

Well-Formedness Invariants

1. Unique parent — Every child has exactly one parent (tracked via Parent: pointer).
2. Complete expansion — Every non-atomic item has at least one child.
3. No orphans — Every child traces back to a root item via parent pointers.
4. Acyclic — Guaranteed by parent pointer direction (children always point up).
5. Leaf consistency — Atomic items have no children.

Procedure

Step 1: Discover the tree

Glob for TODO*.md in the working directory. Sort by N. Read the deepest file.

Step 2: Assess atomicity

Apply the atomicity predicate to every incomplete item. Classify each as LEAF or BRANCH.

Step 3: Act

All items are LEAF: Tree is fully expanded. Report the first incomplete leaf.

Some items are BRANCH: Create the next TODO_{N}.md (where N is the next unused index):

• Expand BRANCH items into children
• Write Decomposes: header with Status: active (or planned for future work)
• Add **Parent:** to each child
• Annotate parents with **Children:**
• If new children are still BRANCH, recurse into a new file

Step 4: Exhaustive First-Pass Requirement (MANDATORY)

Do not stop after one level of decomposition. After each expansion, re-run Step 2 against every newly created child. Continue creating TODO_{N+1}, TODO_{N+2}, ... until a full pass over all incomplete items yields zero BRANCH classifications.

The user should never have to say "break them down further." If they do, you stopped early — the decomposition was incomplete.

Fixpoint rule: decomposition is complete only when applying the atomicity predicate to every incomplete non-deferred item in every file yields LEAF for all of them.

Step 5: Termination check

Each expansion must strictly reduce scope. If children aren't clearly smaller than the parent, flag for human review.

Step 6: Pre-completion self-review (MANDATORY)

Before reporting the breakdown complete, grep the final set of leaf descriptions for these keywords:

• decide, decision, choose, choice, pick between
• investigate, determine, figure out, trace, audit
• explore, assess, evaluate options
• and then, after that, followed by (sequence markers)
• also, plus, as well as (scope-creep markers)

Any match indicates an unexpanded branch. Split the leaf into: (a) the investigation/decision step as its own leaf, (b) the implementation, (c) the verification (tests/docs). Then re-run Step 4.

Atomicity Predicate

A node is a leaf when ALL of:

1. One concern — One file, one method, or one focused edit. Exception: interface + implementation = one concern.
2. One checkpoint — Exactly one build/test verification point.
3. Failure isolation — If it fails, exactly one thing to investigate.

A node is a branch when ANY of:

• Multiple unrelated file operations
• Requires reading new source files to determine approach
• Sub-steps with different verification points
• Mixes concerns (implementation + tests for unrelated code)
• Requires a design decision — any item containing "decide", "choose between", "pick", "determine approach", or presenting two or more options (A / B / (a) / (b)) is BRANCH. Split into: investigate → decide → implement → verify.
• Requires prior investigation — any item starting with "trace", "investigate", "inventory", "audit", "figure out" is an investigation leaf; the implementation that follows is a separate leaf.
• Contains sequence markers — "then", "after", "followed by", "also" in the description signals multiple checkpoints disguised as one item.
• Modifies source + test together for non-trivial logic — if the behavior change requires reasoning (not just a mechanical find/replace), split: implement → update/add tests.

Output Format

File header

# Subtasks: {brief description}

Status: active | planned
Parent: `TODO.md` (or `TODO_{M}.md` if decomposing a sub-item)
Decomposes: #X → (N.1, N.2), #Y → (N.3, N.4)

Item format

## N.1 — {Concise title}
**Parent:** #X

**Create/Modify:** `path/to/File.cs`

{1-3 sentences: what this does, key design decisions if any.}

**Checkpoint:** `{build/test command}` — expected result

For test items, list test cases in a table (name + what it asserts) rather than writing complete test bodies.

Rules

• Item IDs use the file's N as prefix: TODO_3.md items are 3.1, 3.2, 3.3
• Every item has **Parent:** and **Checkpoint:** lines
• Include interface/contract definitions when they ARE the design decision
• Omit complete file contents — the executor reads source files during execution
• When annotating a parent with children, append **Children:** (don't rewrite the item)

Execution Protocol

When executing a leaf node:

1. Read source files at execution time — don't rely on code in the plan being current.
2. Run the checkpoint. Every leaf has a **Checkpoint:** line. Do not mark [DONE] until it passes.
3. Document deviations. If the implementation differs from the plan, add a **Deviation:** note to the leaf before marking [DONE].
4. Do not add scope. If you notice something extra that should be done, note it for the human. Execute exactly what the plan specifies.

Activating a Planned File

When a Status: planned file becomes the next to work on:

1. Change status to Status: active.
2. Verify the breakdown — read source files referenced by each item, check git log for changes since the file was created. The plan was written with incomplete information; the codebase may have evolved.
3. Revise if needed — update, split, merge, or remove items that no longer match reality. Add a **Revised:** note explaining what changed and why.
4. Then execute normally, starting from the first incomplete leaf.

Traversal: "What Do I Work On Next?"

function next_task(files):
    # 1. Find the active file
    active = find file with Status: active
    if active:
        for item in active (in order):
            if item is incomplete and not deferred: return item
        # All items complete — finish this file
        propagate_completion(active)   # mark parents [DONE] in parent file
        delete active                  # REQUIRED — completed files are ephemeral

    # 2. Activate the next planned file
    planned = find lowest-N file with Status: planned
    if planned:
        activate(planned)   # Status: planned → active, verify breakdown
        return next_task(files)

    # 3. No files left — all work complete
    return null

Completion propagation: When all non-deferred children of parent X are [DONE], mark X as [DONE] in the parent file (identified via Parent: header).

MANDATORY: Delete Completed Non-Root Files

When all items in a non-root TODO_N.md are [DONE] (or deferred), you MUST delete the file immediately. Non-root TODO files are ephemeral work-tracking artifacts, not permanent documentation. Root TODO.md is never deleted.

This is not optional. A completed TODO_N.md left on disk creates confusion about what work remains. Delete it in the same response where you mark the last item [DONE].

Edge Cases

• No TODO.md exists: Ask the user.
• Borderline atomic: Break it down. An extra level costs nothing. Default bias = split.
• Expansion doesn't reduce scope: Stop. Flag for human review.
• Mixed leaves and branches: Normal. Only expand branches.
• Execution deviates from plan: Document in the leaf node before marking [DONE]. Propagate significant deviations to sibling leaves.
• Unsure whether to expand: Expand. User asking "break them down further" means you already failed the exhaustive-pass requirement.

Related: Spec Document Auditing

TODO files track execution (how to build). Spec documents in docs/todos/ track what to build — phase-mapped specs with lifecycle management. Use /audit-todos-dlabs to audit spec docs against codebase state, detect completed/stale/outdated specs, and clean up after implementation work. The entry point for specs is docs/todos/ROADMAP.md.