terryyin/phased-planning

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

1. Summarize what you have learned (discoveries, blockers, partial progress).
2. Stash or commit WIP as appropriate (git stash or a draft branch).
3. Decompose the remaining work into phases (see below).
4. Write the plan to ongoing/<short-name>.md or docs/<short-name>.md.
5. 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:

1. Red — Add or extend a test that describes the next slice; confirm one clear failure for the right reason.
2. Green — Smallest change that satisfies the test; no dead code.
3. 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