Cursor rule

1---
2description: "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics."
3alwaysApply: false
4---
5 
6# Plan Release
7 
8> **HARD GATE** — Do NOT run this skill unless `elaborate-spec` has produced a clear spec or the user has already defined the feature in detail. If the problem is still fuzzy, run `elaborate-spec` first.
9> **HARD GATE** — `specs/product/SCOPE_LATEST.yaml` (or legacy `specs/product/SCOPE_LATEST.yaml`) must exist. If missing, run `scope-work` first.
10 
11Synthesize the conversation context into `specs/release-plan.yaml` (index) and shard detail under `specs/epics/`. No new interview — only clarify if something is genuinely ambiguous.
12 
13## Outputs
14 
15| File | Content |
16|------|---------|
17| `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** |
18| `specs/epics/eNN-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
19| `specs/epics/eNN-<slug>/eNNsYY-<slug>.md` | Story spec in [countable-story-format.md](../../docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria |
20| `specs/epics/eNN-<slug>/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task |
21| `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) |
22 
23## Epic Capsule Structure
24 
25All epics use capsule directories (no flat/folder distinction):
26 
27```
28specs/epics/e01-auth-system/
29├── epic.yaml              # Epic manifest
30├── adr/                   # Epic-local ADRs (created lazily)
31├── e01s01-login.md        # Story spec (countable-story-format)
32├── e01s01-tasks.yaml      # Decoupled task checklist
33├── e01s02-jwt.md          # Story spec
34└── e01s02-tasks.yaml      # Decoupled task checklist
35```
36 
37**Rationale:** Capsule dirs achieve change isolation (C9), enable archive pruning (C2/C6), and enforce SRP by decoupling spec `.md` from execution `-tasks.yaml` (C1).
38 
39## Process
40### 1. Draft epics and stories
41 
42From the conversation context, define:
43- **Epics** — `e01`, `e02`, … (stable IDs; WSJF order in `release-plan.yaml` only)
44- **Stories** — `e01s01`, `e01s02`, … with Gherkin acceptance criteria
45 
46WSJF-sort epics: score = (Business Value + Time Criticality + Risk Reduction) / Job Size. Highest score first.
47 
48> **Security risk boost:** If an epic's `specs/security/epics/<id>/THREAT_MODEL.md` identifies HIGH or CRITICAL risk, add +2 to the WSJF numerator (BV + TC + RR + 2) to reflect the urgency of addressing security concerns before they ship. Document the boost in the epic's note field in release-plan.yaml.
49### 2. Write acceptance criteria (Gherkin)
50 
51For each story, write at least one happy-path and one edge-case scenario (countable format §17 if maturity ≥ 3).
52### 3. Write tasks with verify commands
53 
54Every task must have a `verify:` command. No verify command = not a task.
55### 4. Save specs/release-plan.yaml
56 
57> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
58> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
59> (the expectation), not a number you intend to enforce.
60 
61```yaml
62release:
63  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
64  codename: "Feature Name"
65  status: planning          # planning | in_progress | released
66  semantic_release: true
67  bump_hint: minor          # patch | minor | major — CI decides at merge
68epics:
69  - id: e01
70    title: Auth System
71    wsjf: 4.5
72    capsule_dir: epics/e01-auth-system
73  - id: e02
74    title: User Profile
75    wsjf: 3.8
76    capsule_dir: epics/e02-user-profile
77```
78### 5. Save epic manifest (`epic.yaml`)
79 
80Each epic capsule directory contains an `epic.yaml` manifest:
81 
82```yaml
83id: e01
84title: Auth System
85wsjf: 4.5
86total_bcps: 8
87status: in_progress
88stories:
89  - id: e01s01
90    title: Login
91    bcps: 3
92    status: todo
93    spec: e01s01-login.md
94    tasks: e01s01-tasks.yaml
95  - id: e01s02
96    title: JWT Token Management
97    bcps: 5
98    status: todo
99    spec: e01s02-jwt.md
100    tasks: e01s02-tasks.yaml
101```
102### 6. Save story specs (countable-story-format .md)
103 
104Each story becomes a standalone `.md` file following [countable-story-format.md](../../docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios.
105### 7. Save decoupled task files (`-tasks.yaml`)
106 
107Each story has a decoupled `-tasks.yaml` with implementation steps:
108 
109```yaml
110story_id: e01s01
111title: Login
112status: todo
113bcps: 3
114tasks:
115  - id: 1
116    description: "Add login form component tests"
117    verify: "npm test -- login-form.test.tsx"
118    status: todo
119  - id: 2
120    description: "Implement login form with validation"
121    verify: "npm test -- login-form.test.tsx"
122    status: todo
123```
124 
125> **HARD GATE** — Every task MUST have a runnable `verify:` command. No `verify:` = not a task.
126 
127→ verify: `bash scripts/validate-specs-yaml.sh`
128### 7b. Generate bug registry summary
129 
130Read `specs/bugs/registry.yaml` and add a `bugs:` section to `release-plan.yaml` with totals by status (`fixed`, `deferred`, `wontfix`, `open`): `bugs: { total: N, fixed: N, deferred: N, wontfix: N, registry: specs/bugs/registry.yaml }`.
131 
132### 8. Sync execution status
133 
134```bash
135bash scripts/sync-status-from-epics.sh
136```
137### 9. Snapshot on planning close (optional)
138 
139Copy to `specs/product/snapshots/release-<version>/` when the user approves the plan.
140### 10. Suggest next steps
141 
142- Run `assess-impact` before `plan-work` for any story touching existing modules.
143- Run `plan-work` per story for detailed steps inside the epic shard.
144- Run `change-request` if a new requirement arrives mid-flight.
145