planning git:20260905.35922edA

Immutable. This exact content is served forever at /api/v1/blob/8b2126d77e656140.

---
description: Decisions for planning artifacts, proof, updates, and cleanup
alwaysApply: true
---

# Planning

Apply `problem-decomposition.mdc` before writing or revising a plan.

## Route the work

| Condition | Action |
|-----------|--------|
| Parent problem or candidate selection is unresolved | Use **story-decomposition**; do not write an executable plan |
| Selected stories need goal, scope, or examples clarified | Use **story-refinement** in their home seeds |
| One story's goal, scope, and key examples are understood | Use **slice-planning** |
| Existing PLAN has complex, low-confidence, or overrun leaves | Use **slice-plan-refinement** on the same PLAN; create no new artifact |
| Existing PLAN already has clear, cohesive, plausibly commit-sized leaves | Execute directly; a separate refinement pass is optional |
| Completed plan needs aggregate goal/code/process review | Use **execution-retrospective**; it may generate a follow-up PLAN but never executes it |
| Work belongs to a milestone capability | Use GSD discuss/plan; rewrite its executable tasks to satisfy `problem-decomposition.mdc` |
| Input is only a story-decomposition seed | Select one contained story before planning execution |

## Scope discipline

Deliver the understood story conservatively. Unexpected extras add unwanted
complexity, even when intended as improvements. Clarify uncertain behavior when
possible; otherwise assume it is out of scope and tell the developer what was
considered and excluded. If exclusion prevents the stated goal or examples,
resolve that question before dependent planning or implementation. Necessary
implementation details are not extra product scope; speculative generality is.

Refinement is revisable understanding. Discuss changes to goal or scope and
update the home story and active plan together; discovery alone does not
authorize expansion. Each Behavior must serve included scope or a key example;
Structure must enable its immediate next Behavior.

## Required PLAN contents

Keep only information needed for execution, proof, review, or resume:

1. **Source** — seed/story link when applicable.
2. **Goal and scope** — one selected story or explicitly bounded phase outcome,
   including material exclusions and assumptions.
3. **Outside-in proof** — key examples and their demonstration or test signal.
4. **Ordered slices** — capability-named heading, type, status, and proof.
5. **Current decisions** — only choices that constrain remaining work.
6. **Learnings** — only discoveries that change assumptions or remaining slices.

For each slice, record:

```markdown
### N. Capability outcome
Type: Behavior | Structure
Status: planned | in-progress | done
Proof: <observable signal and focused verification>

Behavior: <pre-condition → trigger → post-condition>
```

For Structure, replace `Behavior` with the internal change and the immediate
next Behavior it enables.

## Artifact locations

| Path | Use |
|------|-----|
| `.planning/seeds/SEED-NNN-slug.md` | Parent problem, candidate stories, and refinement in each story's home section |
| `.planning/phases/NN-slug/` | GSD phase artifacts |
| `.planning/quick/NNN-slug/PLAN.md` | Ad-hoc executable plan for a selected story |
| `.planning/codebase/` | Codebase maps |
| `.planning/{PROJECT,REQUIREMENTS,ROADMAP,STATE}.md` | GSD project memory |
| `.planning/PRODUCT-BACKLOG.md` | Ordered queue of unfinished story titles; details stay in home seeds |

Do not add new plans under `ongoing/` or as flat files directly under
`.planning/`. Do not use phase or slice numbers in product code, tests, feature
files, classes, or permanent docs.

## Proof decisions

| Situation | Plan |
|-----------|------|
| Main user behavior | Targeted E2E or another real high-level boundary |
| Edge, error, or pure contract | Focused unit test following `unit-testing.mdc` |
| Existing untested behavior | Regression proof before changing it |
| Multi-beat E2E cannot pass within one inner TDD beat | Keep it `@wip` until green; do not commit red alone |
| Structure slice | Existing external behavior remains green |
| Interim behavior | Name the later slice that removes or replaces it |

Run focused relevant tests at slice boundaries. Do not require the full suite
unless the workflow or developer explicitly requires it.

## Update and cleanup decisions

- While active, keep slice status, brief learnings, and remaining work in the
  PLAN. `execute-plan` must not use `.planning/STATE.md` as slice resume state.
- After a slice, update later leaves when evidence affects only the selected
  story.
- If evidence meets the parent-decomposition escalation conditions in
  `problem-decomposition.mdc`, record the affected seed/story and stop for
  human review instead of continuing.
- Mark a slice done only after relevant tests, cleanup, post-change-refactor,
  plan update, and the Jidoka / commit / push gate required by `execute-plan`.
- When the whole plan is complete, remove spent diary and obsolete SUMMARY
  detail. Keep enduring behavior in tests/product docs and enduring design in
  code/ADRs.
- Reduce each implemented story's refinement detail to **Goal** and **Scope**
  (including exclusions). Remove spent examples, UI sketches, and architectural
  discussion once enduring knowledge is captured above; preserve its anchor,
  completion status, and unfinished sibling stories.