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

Map every checkable final-state promise in the selected contract, including
Current decisions, to an owning leaf and observable proof. Use inline links or
a compact table; no separate artifact. Include applicable promises, not the
whole seed's aspirations; one proof may cover several promises.

Preserve mappings through refinement, replacement, and resume, repointing
replacement leaves before declaring readiness. Orphans leave the plan incomplete;
completed evidence survives unless changes to its covered boundary invalidate it.

For interim replacements, align the affected callers, fixtures, assertions, and
documentation with final success/rejection behavior. Searches locate that scope;
observable behavior proves completion. Keep work bounded to the replacement.

When async ownership changes, require owner-boundary evidence of timely
background failure observation while the named lifecycle owner runs, and
applicable resource cleanup after failure/shutdown. An awaited throw alone
proves neither. Timing comes from the selected lifecycle contract, not arbitrary
timeouts; unchanged ownership adds no obligation or caller propagation tests.

Accept coverage of promises, not passing commands alone. Missing observations
leave the leaf incomplete and return to implementation before refactor or
acceptance. Refactor may report gaps but cannot supply new behavior. Reuse proof
under the execution workflow's existing invalidation policy.

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