| name | phased-planning |
| description | Decompose tasks into phased plans with one behavior per phase. Use when planning new features, breaking down large tasks, when a task has been in progress for over 10 minutes, or when the planning timer hook fires. Triggers on: plan, decompose, phases, break down, task too large, stuck. |
Phased Planning — Task Decomposition
When to use
- Developer asks to plan or decompose a task.
- A phase or sub-phase is too large to implement in one pass.
- You have been working a long time without a written plan — pause and decompose.
If you must pause mid-task
- Summarize what you have learned (discoveries, blockers, partial progress).
- Stash or commit WIP as appropriate (
git stash or a draft branch).
- Decompose the remaining work into phases (see below).
- Write the plan to
ongoing/<short-name>.md or docs/<short-name>.md.
- Report to the developer and wait for their decision if scope is unclear.
Where to put plans
Use ongoing/<short-name>.md or docs/<short-name>.md — informal, temporary. Update as work proceeds; remove or archive when done.
For sub-decomposition of a single phase: ongoing/<plan-name>-<phase-number>-sub-phases.md (or under docs/).
How to decompose into phases (scenario-first)
Default: Split by user-visible outcomes (for a library: API behavior, diagnostics, compatibility), not by “build the abstraction first.”
Order from common / general toward more specific preconditions.
Solutions: Early phases implement a narrow, concrete slice. Later phases generalize only after you see real repetition — not a large generic framework up front.
Regression: If behavior already exists but has no automated test, prefer a dedicated phase: add a regression test and make it pass.
Extending tests: If similar behavior already has tests, extend them; avoid duplicate test code. Keep at most one intentionally failing test while driving a change.
Big refactor: If making the test pass needs a large structural change, plan that structure as its own phase before (or as the first slice of) the feature.
Consumer / integration: When a change is mainly for downstream runners (Cypress, etc.), note which consumer repo must be validated; this repo’s gate remains pnpm test and pnpm lint.
Still too big: Split by one small part of the outcome per phase (one aspect of the postcondition).
Sub-phases (test-led chunks)
When to use: One “phase” still spans several beats. Prefer sub-phases that alternate failing test and minimal fix, instead of front-loading internals.
Pattern:
- Red — Add or extend a test that describes the next slice; confirm one clear failure for the right reason.
- Green — Smallest change that satisfies the test; no dead code.
- Repeat for the next slice.
Plan document
Document intent and structure in the plan. Update when you learn something that changes remaining work. Remove text that no longer helps the current snapshot.
Include:
- Phases with status (done / in-progress / planned)
- Key design decisions and rationale
- Discoveries that affect remaining work
