planning · diff
git:20260905.e6ea35d to git:20260905.35922ed
25 added, 30 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 |
|-----------|--------|
- | 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** |
+ | 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. **Outcome and boundaries** — one selected story or the explicitly bounded
- phase outcome.
- 3. **Outside-in proof** — example, demonstration, E2E, or high-level unit signal.
+ 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` | Non-executable parent problem and candidate stories |
+ | `.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.