Windsurf rules

1---
2name: plan-work
3model: opus
4description: "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2)."
5---
6 
7# story: e45s29
8 
9# Plan Work
10 
11> **Spine position:** Step 3 — scope-work → slice-tasks → plan-work.
12 
13Produce a detailed, verifiable implementation plan in the **active epic capsule directory** (`specs/epics/eNN-slug/`). Output: a story spec `.md` file (countable-story-format) and a decoupled `eNNsYY-tasks.yaml` with runnable verify commands. "I think it works" is not a step.
14 
15> **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, convert the task into "step → verify: `<cmd>`" pairs here before writing tasks — every task ships a runnable `verify:` or the plan is not done.
16>
17> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
18 
19## Pre-flight
20 
21Read: `release-plan.yaml`, `product/SCOPE_LATEST.yaml`, active `epics/<capsule>/epic.yaml`, `tech-architecture/tech-stack.md`, `product/GLOSSARY_LATEST.yaml`.
22 
23> **ZOOM-OUT MANDATE** (v1.17.0) — If modifying an existing module: (1) State the module's **purpose**. (2) Name its **callers**. (3) List its **contracts**. Cannot answer all three? Stop — scope is misunderstood.
24 
25If this plan touches an existing module, run `assess-impact` first to understand blast radius.
26 
27> **DISCOVERY MANDATE** (v1.18.0) — For external API integration, verify the API signature via local docs or search and quote at least one technical detail in the step's context.
28 
29> **MULTIPLE INTERPRETATIONS (HARD GATE)** — If the task admits ≥2 valid interpretations, list them and get a user decision before drafting any steps.
30 
31> **COMPLEXITY PUSHBACK (HARD GATE)** — Every new abstraction MUST include a one-sentence "Reason for Depth." If it can't be filled non-trivially, the abstraction is premature — use inline code instead.
32 
33> **SLOPCHECK (HARD GATE)** — For every external package, tag it `[OK]`, `[SUS]`, or `[SLOP]`. `[SUS]`/`[SLOP]` require human approval before execution.
34 
35## Invocation modes
36 
37- Default: full plan with zoom-out mandate, impact assessment, slopcheck
38- `--fast`: Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.
39 
40## Process
41 
42> **Timing:** `bash scripts/bp-timing.sh start plan-work` at invocation; `bash scripts/bp-timing.sh end plan-work` before handoff.
43 
441. **Explore** — Use `Explore` subagent to understand affected modules, existing test patterns, similar prior art, and dependencies.
45 
462. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.
47 
483. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics/<id>/THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. Each task should also include an `allure:` block to drive test reporting: `severity:` maps risk to Allure severity (`P0→critical`, `P1→high`, `P2→normal`, `P3→minor`), and `categories:` is a list of relevant tags like `"Security Review"`, wave names, or test categories (see REFERENCE.md for the full template).
49 
50   **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content:
51 
52   | Tag | When | Required content |
53   |-----|------|------------------|
54   | `ADDED` | New requirement | Full requirement text |
55   | `MODIFIED` | Changed behavior | **Before:** prior behavior · **After:** new behavior |
56   | `REMOVED` | Retired requirement | **Before:** what existed · **After:** (removed) + rationale |
57   | `RENAMED` | ID or title change only | **Before:** old ID/title · **After:** new ID/title |
58 
59   Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate.
60 
614. **Verify step format** — Every step MUST follow: `N. <What to do> → verify: <runnable command>`. See [REFERENCE.md](REFERENCE.md) for good/bad examples.
62 
634a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run:
64 
65```bash
66bash scripts/lib/plan-consistency-check.sh specs/epics/&lt;capsule&gt;/
67```
68 
69Print CRITICAL / HIGH / MED findings. **CRITICAL or HIGH blocks code generation** — fix capsule artifacts first. MED requires explicit user acknowledgment.
70 
714b. **tasks.yaml failing ledger (e45s06)** — Every new task entry starts with `status: failing`. Only flip to `status: passing` after its `verify:` command exits 0 during `develop-tdd` or `verify-work`. Never pre-mark passing at plan time.
72 
735. **Review with user** — Confirm step order, granularity, and that verify commands are runnable in this project.
74 
75## Lifecycle Gates (e45s09)
76 
77| Gate | When | Pass condition |
78|------|------|----------------|
79| **Pre-Implementation** | Before `kickoff-branch` / first RED commit | Root-cause stated for bugs; `assess-impact` done for module changes; plan-consistency-check PASS |
80| **Validation** | Story marked done | All tasks `status: passing`; verify evidence in `specs/verifications/` |
81| **Reopen-don't-refile** | Regression on shipped story | Reopen existing story/bug — do not create duplicate capsule entries |
82 
83After writing capsule tasks, suggest `kickoff-branch` (if not already on a feature branch) then `build-epic`, `execute-plan`, or `develop-tdd`.
84 
85## Verify
86 
87→ verify: `test -f scripts/lib/plan-consistency-check.sh && EPIC=$(ls -d specs/epics/*/ 2>/dev/null | grep -v archive | sort | head -1) && test -n "$EPIC" && bash scripts/lib/plan-consistency-check.sh "$EPIC" >/dev/null 2>&1`
88 
89 
90 
91## Handoff
92 
93Gate: READY -> next: kickoff-branch
94Writes: state.yaml handoff.next_skill = kickoff-branch
95 
96 
97<!-- story: e01s01 -->
98<!-- story: e02s02 -->
99<!-- story: e06s01 -->
100<!-- story: e06s02 -->
101 
102---
103 
104# Plan Work — Reference
105 
106## Navigation
107 
108| Lines | Section |
109|-------|---------|
110| 1 | Title |
111| 3–25 | Navigation |
112| 26–27 | Output file formats |
113| 28–31 | Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md` |
114| 32–61 | Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml` |
115| 62–64 | Plan template |
116| 65–71 | Story [X.Y]: [title] — Implementation Steps |
117| 72–77 | Steps |
118| 78–85 | Verification Script (Step-by-Step) |
119| 86–89 | Out of scope |
120| 90–94 | Risks |
121| 95–114 | Verify step format rules |
122| 115–116 | Sub-operations |
123| 117–127 | Risk Assignment Heuristics |
124| 128–143 | Requirement delta tags (e45s29) |
125| 144–152 | Define Success |
126| 153–161 | Zoom-Out Check |
127| 162–169 | Slopcheck |
128 
129## Output file formats
130 
131### Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md`
132 
133Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.
134 
135### Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml`
136 
137```yaml
138story_id: e01s01
139title: Login
140status: failing
141bcps: 3
142tasks:
143  - id: 1
144    description: "Add login form component tests"
145    verify: "npm test -- login-form.test.tsx"
146    risk: P1
147    status: failing   # flip to passing only after verify exits 0 (e45s06)
148    allure:
149      severity: high              # P0→critical, P1→high, P2→normal, P3→minor
150      categories:
151        - "Auth"
152        - "Security Review"
153```
154 
155**Allure severity mapping:**
156- `P0` → `critical`
157- `P1` → `high`
158- `P2` → `normal`
159- `P3` → `minor`
160 
161`categories` is a list of relevant tags — wave names, test categories (e.g. `"unit"`, `"integration"`), or thematic groupings (e.g. `"Security Review"`).
162 
163Update `specs/epics/<capsule>/epic.yaml` manifest to list the story and its BCPs. Run `bash scripts/sync-status-from-epics.sh` after structural changes.
164 
165## Plan template
166 
167```
168### Story [X.Y]: [title] — Implementation Steps
169 
170**type:** feat | fix | refactor
171**risk:** P0 | P1 | P2 | P3
172**context:** domain | infra
173**Context**: [One paragraph: what this story implements and why]
174 
175## Steps
176 
1771. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
1782. [Step description] (ref: ADR-NNNN or commit SHA) → verify: `<runnable command>`
179...
180 
181## Verification Script (Step-by-Step)
182 
183[A human-readable, step-by-step script for the user to verify the story's outcome.]
184 
1851. [Action 1: e.g. Start the server]
1862. [Action 2: e.g. Open browser to http://localhost:3000]
1873. [Observation: e.g. Verify that the login modal appears]
188 
189## Out of scope
190 
191- [Explicit exclusions]
192 
193## Risks
194 
195- [Anything that could go wrong and how to detect it early]
196```
197 
198## Verify step format rules
199 
200Every step MUST follow this exact format:
201```
202N. <What to do> → verify: <runnable command that proves it worked>
203```
204 
205**Good examples:**
206```
2071. Add User model with email and name fields → verify: npm test -- user.test.ts
2082. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
2093. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts
210```
211 
212**Bad examples (no verify command):**
213```
2141. Implement the user creation flow
2152. Write tests for the API
216```
217 
218## Sub-operations
219 
220### Risk Assignment Heuristics
221 
222Every task and story MUST be assigned a `risk:` level (P0, P1, P2, P3). When `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` exists for the epic, defer to its scenario risk mapping (`SC-eNNsYY-P0-NN`). Otherwise, apply these heuristics based on BCP and story type:
223 
224- **P0**: Critical path, data loss risk, auth/security boundary, external integration, or high BCP (≥ 5).
225- **P1**: Core feature logic, state mutations, standard business value (BCP 3-4).
226- **P2**: Utility functions, UI layout changes, display-only data, low risk (BCP 2).
227- **P3**: Documentation, cosmetic tweaks, CSS variables, zero behavioral change (BCP 1).
228 
229`verify-work` scales its UAT depth based on this field.
230 
231### Requirement delta tags (e45s29)
232 
233When modifying existing behavior in story spec § Requirements:
234 
235```markdown
236#### MODIFIED: User can reset password via email link
237**Before:** Password reset required admin approval.
238**After:** Self-service reset via signed email link (expires 1h).
239 
240#### REMOVED: Legacy OAuth1 login
241**Before:** OAuth1 provider supported for enterprise SSO.
242**After:** (removed) — provider deprecated; OAuth2 only.
243```
244 
245Tags: `ADDED`, `MODIFIED`, `REMOVED`, `RENAMED`. `MODIFIED`/`REMOVED`/`RENAMED` without before/after → plan-work gate FAIL.
246 
247### Define Success
248 
249Before planning, convert task statements into observable "step → verify: <cmd>" pairs:
250- Break the task into observable outcomes (behaviors) rather than implementation steps
251- Write pairs in the format: `[What must be true] → verify: <runnable command>`
252- Challenge completeness: are all required behaviors covered?
253- Get user confirmation: "Does this capture everything the task requires?"
254- Once confirmed, these pairs become the skeleton for plan-work steps
255 
256### Zoom-Out Check
257 
258When modifying an existing module, confirm scope is understood:
259- State the module's **purpose** — what is it responsible for?
260- Name the **callers** — who depends on it?
261- List the **contracts** — what invariants or interfaces must be preserved?
262 
263If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.
264 
265### Slopcheck
266 
267For every external package proposed in the plan, tag each with one of:
268- `[OK]` — package is mature, actively maintained, appropriate scope
269- `[SUS]` — suspiciously broad, has maintenance concerns, or unclear fit
270- `[SLOP]` — unmaintained, known security issues, or out of scope
271 
272`[SUS]` and `[SLOP]` require explicit human approval before the step may execute. Document tags inline next to the package name.
273