planning · diff
git:20260905.35922ed to git:20260905.7a99c9b
24 added, 0 removed. Audit A to A.
---
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
+ 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.
- 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.