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

planning-tasks