---
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

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