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