Cursor rule

1---
2description: "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning-status.yaml) through survey-context → scope-work → research-first → elaborate-spec → plan-release → slice-tasks. NOT a duplicate of plan-work or the planning spine; it orchestrates the pre-coding discover phase only."
3alwaysApply: false
4---
5 
6# story: e24s03
7 
8# Run Planning
9 
10> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
11>
12> **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
13 
14Updates `specs/planning-status.yaml` as discover-phase skills complete. This is NOT a duplicate of plan-work — it orchestrates the *pre-coding* discovery phase only (Discover phase in the 6-phase PMBOK lifecycle), handing off to the planning spine for implementation detail.
15 
16## When to use
17 
18- Starting a brand-new feature or initiative with no prior planning artifacts
19- Returning to a stalled initiative and needing to resume the discovery workflow
20- After `orchestrate-project` hands off to the Discover phase
21- When a new epic emerges from `change-request` and needs to go through full discovery
22 
23## Pre-flight
24 
25- [ ] Does `specs/planning-status.yaml` exist? If not, create it with the default workflow keys.
26- [ ] Does `specs/state.yaml` have `active_flow: planning`? Set it if not already.
27- [ ] Is the epic identified in `release-plan.yaml`? The epic must exist before discovery begins.
28 
29## Workflows (default keys)
30 
31- `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
32 
33Each key maps to a skill invocation. Optional keys can be skipped; required keys must complete before the phase advances.
34 
35## Process
36 
371. **Read state** — Read `specs/planning-status.yaml` and `specs/state.yaml`. Understand where discovery stands: which workflow keys are `done`, which are `pending`, and which are `optional` (can be skipped).
38 
392. **Find next step** — Find the first workflow key with `status: pending`. If the key is `optional`, check if the user wants to run it. If not, mark it `skipped`.
40 
412a. **Context capsule check** — Before invoking `elaborate-spec`, check whether a fresh `specs/planning-context.yaml` exists:
42```bash
43   test -f specs/planning-context.yaml && python3 -c "
44import yaml, datetime
45d = yaml.safe_load(open('specs/planning-context.yaml'))
46written = d.get('written_at','')
47if written:
48    age = (datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(written)).total_seconds() / 3600
49    print(f'Context age: {age:.1f}h')
50" 2>/dev/null || echo "No context or no written_at"
51```
52   - If context is **< 24h old**, ask: `"Planning context from Xh ago exists for '<feature_name>'. Re-run elaborate-spec? [y/N]"`. Skip elaborate-spec on N.
53   - If context is **≥ 24h old** or absent, run elaborate-spec normally.
54   - On planning cycle completion (all required keys done), clear the capsule: delete `specs/planning-context.yaml` and set `planning-status.yaml` `context_capsule: null`.
55 
563. **Invoke the matching skill** — Run the skill that matches the workflow key:
57   - `survey-context` — where are we?
58   - `scope-work` — what's in and out?
59   - `research-first` — what already exists?
60   - `elaborate-spec` — refine the idea (optional)
61   - `plan-release` — sequence epics by WSJF
62   - `slice-tasks` — cut vertical slices
63 
644. **Update status** — On successful completion, set `status: done` for that workflow key in `planning-status.yaml`.
65 
665. **Advance** — Set `state.yaml` `active_flow: planning` while in this chain. When all required keys are done, set `handoff.next_skill` to `plan-work`.
67 
68## Workflow Keys Schema
69 
70In `specs/planning-status.yaml`:
71```yaml
72context_capsule:             # written by elaborate-spec; cleared on cycle completion
73  written_at: "2026-06-22T03:00:00Z"
74  written_by: elaborate-spec
75  feature_name: "add dark mode"
76workflows:
77  survey-context:
78    required: true
79    status: done
80  scope-work:
81    required: true
82    status: pending
83  research-first:
84    required: false
85    status: optional
86    note: "Skip if no external dependencies"
87  elaborate-spec:
88    required: false
89    status: optional
90  plan-release:
91    required: true
92    status: pending
93  slice-tasks:
94    required: true
95    status: pending
96```
97 
98## Verify
99 
100→ verify: `test -f specs/planning-status.yaml && [ "$(grep -c 'status: done' specs/planning-status.yaml)" -ge 3 ]`
101