Planning Tasks

Takes design.md and definition.md from docs/issues/YYYY-MM-DD-<slug>/ as input. Produces a task plan detailed enough for a coding agent to execute without re-deriving implementation from the design.

Does NOT introduce new design decisions, modify the design, or write complete implementations.

EVERY TASK MUST HAVE ALL 8 FIELDS — NO EXCEPTIONS

Workflow

• Step 1: Load Inputs
• Step 2: Explore Codebase
• Step 3: Break Design into Tasks
• Step 4: Order Tasks & Dependencies
• Step 5: Out-of-Scope Tasks
• Step 6: Open Execution Questions
• Step 7: Readiness Declaration
• Step 8: Validate

Step 1: Load Inputs

Read design.md and definition.md from the issue folder. Extract: design goals, non-goals, proposed design, current state.

Step 2: Explore Codebase

• Read files referenced in issue definition's current state

• Identify patterns, naming conventions, testing style

• Locate exact insertion points for new code

No output section — ensures tasks reference real paths and patterns.

Step 3: Break Design into Tasks

Start ## Task List with a Task Index — one line per task:

T1: Add timing instrumentation [S] — T2: Refactor task queue [M] — T3: Add action selector [L]

Each task MUST use this exact format:

T<N>: <short imperative title> [S|M|L]

Objective: One outcome, traceable to a design element. Size: S (single file, <30 lines) | M (2-3 files, moderate logic) | L (multiple files, complex state/logic) Files:

• Create: exact/path/to/new_file.ts
• Modify: exact/path/to/existing.ts
• Test: tests/path/to/test.test.ts Implementation:

1. In path/to/file.ts: add import X, modify functionName() to do Z
2. In tests/path/to/test.test.ts: test "should X" — assert Y Boundaries: What this task must NOT do Dependencies: T<N> | None Expected Outcome: Observable result (file exists, test passes, etc.) Validation: exact command — expected output

Code detail guidance:

• ✓ Interfaces, type definitions, function signatures

• ✓ Key logic as pseudocode or commented outline

• ❌ Complete function bodies

• ❌ Complete test implementations

All tasks must have the same depth of specificity. If a task requires the executing agent to choose between approaches, resolve the choice or flag it in Open Execution Questions.

Step 4: Order Tasks & Dependencies

Explain sequencing rationale. Identify parallel vs sequential tasks.

Step 5: Out-of-Scope Tasks

List tasks that might be assumed necessary but are excluded. Reference design non-goals.

Step 6: Open Execution Questions

List execution uncertainties (tooling, environment, access). Do NOT resolve — only list. Write "No open execution questions identified." if none.

Step 7: Readiness Declaration

Exactly one: Ready for execution | Blocked pending clarification | Requires design update

Step 8: Validate

Check Criteria

Task fields All 8 fields present on every task

Task Index Present at top of Task List

Implementation Specific changes per file, signatures complete, bodies are outlines

Traceability Every task traces to proposed design

Outcomes No vague outcomes ("improved", "refactored")

Validation Exact commands with expected output

File paths Match actual codebase (from Step 2)

Consistency No task significantly vaguer than others

Decisions No embedded design decisions — resolve or flag in Open Execution Questions

If any check fails, return to the failing step and revise.

Output

Save to docs/issues/YYYY-MM-DD-<slug>/plan.md .

Task List

Task Ordering Rationale

Out-of-Scope Tasks

Open Execution Questions

Readiness Declaration

Missing any section invalidates the output.

Anti-patterns

• ❌ 50-line function body → ✓ signature + outline

• ❌ Full test code → ✓ test descriptions with expected assertions

• ❌ "Update the function" → ✓ "In executeTask() (~line 45), add X"

• ❌ No goal reference → ✓ "Objective: ... (design goal #1)"

• ❌ "Either add new RPC or extend existing" → ✓ pick one or flag

• ❌ T1 has exact insertion points, T8 says "add component" → ✓ same depth