planning git:20260905.1736449A

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

---
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 |
|-----------|--------|
| Problem, value, expected outcome, or story boundaries are unresolved | Use **story-decomposition**; do not write an executable plan |
| One story-sized outcome is selected | 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 |

## Required PLAN contents

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

1. **Source** — seed/story link when applicable.
2. **Outcome and boundaries** — one selected story or the explicitly bounded
   phase outcome.
3. **Outside-in proof** — example, demonstration, E2E, or high-level unit 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` | Non-executable parent problem and candidate stories |
| `.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.