1---
2name: story
3description: '[Project Management] Use when creating user stories from PBIs, slicing features, or breaking down requirements.'
4metadata:
5 source: https://skillmd.com/skills/duc01226/story
6---
7
8> Codex compatibility note:
9>
10> - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references.
11> - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
12> - User-question prompts mean to ask the user directly in Codex.
13> - Ignore Claude-specific mode-switch instructions when they appear.
14> - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
15> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
16> - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
17> - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
18> - If a required step/tool cannot run in this environment, stop and ask the user before adapting.
19
20<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->
21
22## Codex Project-Reference Loading (No Hooks)
23
24Codex uses static project-reference loading instead of runtime-injected project docs.
25When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
26
27**Always read:**
28
29- `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings)
30- `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog)
31- `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns)
32
33**Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=<key>`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it.
34
35**Situation-based docs:**
36
37- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md`
38- Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md`
39- Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md`
40- Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`
41- Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above
42- Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/`
43- Integration test implementation/review: `integration-test-reference.md`
44- E2E test implementation/review: `e2e-test-reference.md`
45- Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files
46
47Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task.
48
49<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->
50
51<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->
52
53> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
54> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.
55> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.
56> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
57
58<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->
59
60## Quick Summary
61
62**Goal:** Produce sprint-ready, INVEST-valid user stories — tech-agnostic, testable GWT criteria, evidence-cited estimates, dependency-mapped — by breaking Product Backlog Items into implementable stories via vertical slicing and SPIDR splitting, so a team with zero codebase knowledge can implement on any stack.
63
64**Summary:**
65
66- **Main steps (the pipeline):** (1) read PBI + active plan, load domain context — module, entities, BR-IDs; (2) identify VERTICAL end-to-end slices; (3) SPIDR-split anything SP >8 (MUST) / >5 (SHOULD) until INVEST-valid; (4) write each story with min 3 GWT scenarios + 1 authorization scenario; (5) estimate bottom-up (Blast-Radius pre-pass → phase-hours → days; SP DERIVED) and emit full estimate frontmatter; (6) emit Story Dependencies table (no orphans); (7) run MANDATORY ask the user directly validation; (8) save to `team-artifacts/pbis/stories/{YYMMDD}-ba-story-{slug}.md`; (9) suggest `$spec [mode=tests]` next.
67- Slice VERTICALLY (thin end-to-end), NEVER horizontally (backend/frontend split) — apply SPIDR (Spike/Paths/Interfaces/Data/Rules) until each story is INVEST-valid — why: horizontal slices delay deliverable user value.
68- Every story is tech-agnostic + rebuild-from-scratch + demoable (AI-SDD M1-M5 and M7): no framework/class/file names in prose, carry the inherited `FR-`/`BR-` logical ID plus a `[Source: namespace/service/id]` abstract anchor (NEVER `file:line`), and every criterion states an outcome a stakeholder could SEE — reject and rework on any STOP condition.
69- Min 3 GIVEN/WHEN/THEN scenarios (happy + edge + error) PLUS a mandatory authorization scenario per story; every criterion has exactly ONE observable interpretation.
70- Estimate bottom-up (phase-hours → days × productivity factor; SP DERIVED, never the driver) with explicit `test_count` and Blast-Radius pass; emit full `man_days_*` / `risk_*` / `blast_radius` / `estimate_reasoning` frontmatter — why: SP-first anchors to a guess, downstream `$prioritize`+`$plan` read these fields.
71- Story Dependencies table is mandatory (no orphan stories) and the ask the user directly validation interview runs before handoff — NEVER auto-decide slicing/scope/effort.
72
73> **MANDATORY IMPORTANT MUST ATTENTION** Plan ToDo Task to READ the following project-specific reference docs:
74>
75> - `project-structure-reference.md` -- project patterns and structure
76> - `docs/project-reference/domain-entities-reference.md` — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
77> - `docs/specs/` — Test specifications by module (read existing TCs for related features; include test story/acceptance criteria for new stories)
78>
79> If file not found, search for: project documentation, coding standards, architecture docs.
80
81**Workflow:**
82
831. **Read PBI** — Load PBI artifact, acceptance criteria, and domain context
842. **Vertical Slice** — Identify end-to-end slices of functionality
853. **SPIDR Split** — Apply Spike/Paths/Interfaces/Data/Rules splitting if effort >5
864. **Write Stories** — INVEST-validated stories with min 3 GIVEN/WHEN/THEN scenarios each
875. **Validate** — Interview user to confirm slicing, acceptance criteria, and effort estimates
88
89**Key Rules:**
90
91- Slice VERTICALLY (thin end-to-end); NEVER horizontally (backend/frontend split) — why: a horizontal slice ships no user-visible value on its own.
92- SP >8 MUST ATTENTION be split; >5 SHOULD be split — apply SPIDR until each story is INVEST-valid.
93- Every story MUST ATTENTION carry `story_points`, `complexity`, `man_days_traditional`, `man_days_ai` — plus the `risk_*` / `blast_radius` / `estimate_reasoning` fields `$prioritize` and `$plan` read downstream.
94- SP is DERIVED from bottom-up phase-hours → days × productivity factor — NEVER the driver.
95- Min 3 GIVEN/WHEN/THEN scenarios (happy + edge + error) PLUS a mandatory authorization scenario; each criterion has exactly ONE observable interpretation.
96- Tech-agnostic prose ONLY — no framework/class/file names; anchor with `[Source: namespace/service/id]`, NEVER `file:line`.
97- Story Dependencies table is mandatory — NEVER leave an orphan story.
98- Run the ask the user directly validation interview before handoff — NEVER auto-decide slicing, scope, or effort.
99
100### Frontend/UI Context (if applicable)
101
102> When the task involves frontend or UI changes, read:
103
104- Component patterns: `docs/project-reference/frontend-patterns-reference.md`
105- Styling/BEM guide: `docs/project-reference/scss-styling-guide.md`
106- Design system tokens: `docs/project-reference/design-system/README.md`
107
108## Greenfield Mode
109
110> **Auto-detected:** no existing codebase (no discovered source directories, no manifest files, no populated `project-config.json`) → greenfield mode switches on automatically. Planning artifacts (`docs/`, `plans/`, `.claude/`) do NOT count — the repository needs actual code directories with content.
111
112**When greenfield is detected:**
113
1141. Generate **foundation PBIs** instead of feature stories: infrastructure setup, project scaffold, CI/CD pipeline, first feature vertical slice
1152. Dependency ordering: infrastructure stories BEFORE feature stories
1163. Skip the `project-structure-reference.md` read — it will not exist
1174. Include setup stories: dev environment, build tooling, deployment pipeline, monitoring
1185. Priority order: infra → scaffold → first feature → remaining features
1196. **[CRITICAL] Architecture Scaffolding Story:** FIRST story = "Architecture Scaffolding" — every OOP/SOLID base abstract class, generic interface, and infrastructure abstraction the chosen stack needs. AI self-investigates which base classes the project requires; every feature story depends on it — why: features built on an unscaffolded foundation encode the wrong abstractions permanently.
1207. Scaffolding acceptance criteria: base classes compile/type-check, DI/IoC registrations resolve, smoke test passes
1218. **UI System Foundation Story:** If the project has a frontend, generate a "UI System Foundation" story (Sprint 0) with these sub-stories:
122
123 | Sub-Story | SP | Priority | Depends On |
124 | ------------------------------------------------------------------------- | --- | --------- | ------------------------ |
125 | "Set up design token system" | 2-3 | Must Have | Architecture Scaffolding |
126 | "Create base layout and responsive grid" | 2-3 | Must Have | Design tokens |
127 | "Create core UI components (loading, error, empty, toast, button, input)" | 3-5 | Must Have | Design tokens + layout |
128
129**Dependency rule:** All UI feature stories MUST ATTENTION depend on "UI System Foundation" stories.
130
131- Each story needs happy path, edge case, and error scenario (minimum)
132- Use correct project domain vocabulary when available (check project docs for terminology)
133
134**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**
135
136# User Story Creation
137
138Break Product Backlog Items into implementable user stories using vertical slicing and SPIDR patterns.
139
140---
141
142## Step 0: Locate Active Plan (if in workflow)
143
144If running within a workflow (big-feature, greenfield-init, etc.):
145
1461. **Search for active plan** — Glob `plans/*/plan.md` sorted by modification time, or check the current task list for plan context
1472. **Read `plan.md`** — understand project scope, architecture decisions, domain model, implementation plan
1483. **Read existing research** — `{plan-dir}/research/*.md` and `{plan-dir}/phase-*.md` for domain model, tech stack, architecture
1494. **Read `docs/project-reference/domain-entities-reference.md`** (if exists) — understand existing domain entities for accurate story scoping
1505. Use plan context to inform story slicing (architecture decisions affect how stories are split)
151
152---
153
154## When to Use
155
156- PBI ready for story breakdown
157- Feature needs vertical slicing
158- Creating sprint-ready work items
159- Story too large (effort >8)
160
161---
162
163## Quick Reference
164
165### Workflow
166
1671. Read PBI artifact and acceptance criteria
1682. **Load domain context** (if project module detected)
1693. Identify vertical slices (end-to-end functionality)
1704. **Apply SPIDR splitting** if stories too large
1715. Apply INVEST criteria to each story
1726. Create user stories with GIVEN/WHEN/THEN (min 3 scenarios)
1737. Save to `team-artifacts/pbis/stories/`
1748. **Validate stories** (MANDATORY) - Interview user to confirm slicing, acceptance criteria, and effort
1759. Suggest next: `$spec [mode=tests]` or `$design-spec`
176
177### Output
178
179- **Path:** `team-artifacts/pbis/stories/{YYMMDD}-us-{pbi-slug}.md`
180- **Format:** Single file with all stories (use ## headers per story)
181
182> **Artifact Path (canonical convention)** — Command `$story` → base path `team-artifacts/pbis/stories/`, role token `ba`, type `story`. General filename pattern: `{YYMMDD}-{role}-{type}-{slug}.md` → e.g. `260119-ba-story-invoice-approval.md`. Slug = lowercased basename, non-alphanumeric → `-`, trimmed, max 50 chars.
183
184---
185
186## Project Domain Context Loading
187
188When slicing domain-related PBIs, automatically load business context.
189
190### Step 1: Detect Module
191
192**From PBI frontmatter:**
193
1941. Check `module` field
1952. If missing, detect module from `docs/specs/` directory names
196
197### Step 2: Load Feature Context
198
199```
200Glob("docs/specs/{module}/*.md")
201```
202
2031. Read module README (first 200 lines)
2042. Identify related feature from `related_features` list
2053. Extract existing business rules (BR-{MOD}-XXX)
2064. Note entity names from feature docs
207
208### Step 3: Apply Domain Vocabulary
209
210Read `docs/project-config.json` modules[] and `docs/specs/` to detect domain vocabulary per module. Use entity names from feature docs — avoid ambiguous synonyms.
211
212### Step 4: Include in Story
213
214```markdown
215## Domain Context
216
217**Module:** {detected module}
218**Feature:** {related feature}
219**Entities:** {Entity1}, {Entity2}
220**Business Rules:** BR-{MOD}-XXX (from feature docs)
221```
222
223---
224
225## INVEST Criteria
226
227| Criterion | Definition | Validation Question |
228| --------------- | -------------------------------- | ------------------------------------ |
229| **I**ndependent | No dependencies on other stories | Can this be developed in any order? |
230| **N**egotiable | Details can change | Is the "how" open for discussion? |
231| **V**aluable | Delivers user value | Does user get observable benefit? |
232| **E**stimable | Can estimate story points | Can team size this? (Fibonacci 1-21) |
233| **S**mall | Completable in sprint | SP ≤8? (prefer ≤5) |
234| **T**estable | Clear acceptance criteria | Can we write pass/fail tests? |
235
236---
237
238## SPIDR Splitting Checklist
239
240**When to apply:** Story SP >8 MUST ATTENTION split. SP >5 SHOULD split. SP 13 = SHOULD split into 2-3 stories. SP 21 = MUST ATTENTION split (epic-level).
241
242| Pattern | Question | Split Strategy |
243| -------------- | ---------------------------- | ----------------------------------------- |
244| **S**pike | Unknown complexity? | Create research spike first, then stories |
245| **P**aths | Multiple workflow branches? | One story per path/choice |
246| **I**nterfaces | Multiple UIs or APIs? | One story per interface |
247| **D**ata | Multiple data formats/types? | One story per data variation |
248| **R**ules | Multiple business rules? | One story per rule variation |
249
250### Splitting Examples
251
252**Paths:** "User can pay by card OR PayPal" → Story A: Card payment, Story B: PayPal payment
253
254**Data:** "Import CSV, Excel, JSON" → Story A: CSV import, Story B: Excel import, Story C: JSON import
255
256**Rules:** "Different approval flows by amount" → Story A: <$1000 auto-approve, Story B: >$1000 manager approval
257
258### Size Validation
259
260```
261SP 1-5: ✅ Good size
262SP 6-8: ⚠️ Consider splitting (apply SPIDR)
263SP 13: ❌ SHOULD split into 2-3 stories
264SP 21: ❌ MUST ATTENTION split — epic-level, not sprint-ready
265```
266
267---
268
269## Scenario Templates
270
271**Minimum 3 scenarios per story:**
272
273### 1. Happy Path (Positive)
274
275```gherkin
276Scenario: User successfully {completes action}
277 Given {user has required permissions/state}
278 And {required data exists}
279 When user {performs valid action}
280 Then {primary expected outcome}
281 And {secondary verification if needed}
282```
283
284### 2. Edge Case (Boundary)
285
286```gherkin
287Scenario: System handles {boundary condition}
288 Given {edge state: empty list, max items, zero value}
289 When user {attempts action at boundary}
290 Then {appropriate handling: pagination, warning, default}
291```
292
293### 3. Error Case (Negative)
294
295```gherkin
296Scenario: System prevents {invalid action}
297 Given {precondition}
298 When user {provides invalid input OR unauthorized action}
299 Then error message "{specific error message}"
300 And {system remains in valid state}
301 And {no partial changes saved}
302```
303
304### 4. Authorization (MANDATORY per story)
305
306```gherkin
307Scenario: Unauthorized user cannot {perform action}
308 Given user has role {unauthorized role}
309 When user attempts to {action}
310 Then system rejects with "Forbidden" or "Unauthorized"
311 And no data is modified
312```
313
314### Additional Scenario Types
315
316**Performance:** Response time under load
317**Concurrency:** Simultaneous user actions
318**Integration:** External service unavailable
319
320---
321
322## AI-SDD Mandate Gate (M1-M5 and M7) — BLOCKING
323
324See `.claude/skills/shared/sdd-artifact-contract.md` → "AI-SDD Mandates (M1-M7)" for BLOCKING criteria. Every generated story MUST satisfy M1-M5 and M7:
325
326- **Separate intent from implementation (M1/M2):** The story narrative and acceptance criteria stay tech-agnostic — describe observable business behavior, no framework/product/language/design-pattern names, no source identifiers. Keep optional hints in `## Technical Notes` and source references in evidence carriers as stack-portable abstract anchors (`[Source: namespace/service/id]`, never `file:line`). Prose follows `docs/project-reference/spec-principles.md` §3.
327- **Logical Requirement ID (M3):** Each story carries a logical requirement ID (`FR-`/`BR-`) inherited from its parent PBI as the PRIMARY citation spine; keep the `[Source: namespace/service/id]` abstract anchor as a SECONDARY, stack-portable carrier — KEEP it, never remove it and never replace it with `file:line` (physical coordinates live only in the provenance sidecar).
328- **Testable GWT/EARS criteria (M4):** Every Given/When/Then or EARS criterion has ONE valid interpretation, observable completion states, and named failure modes — no vague phrasing ("fast", "user-friendly", "handle appropriately") and no implementation details.
329- **Rebuild-from-scratch (M5):** A team with zero codebase knowledge can implement identical behavior on ANY stack from the story alone.
330- **Business-visibility (M7):** Apply the demo test to each criterion's BODY: _"what would a stakeholder SEE change?"_ — no answer → FAIL as TECHNICAL-ONLY and drop it from the story. Every `GIVEN` = a state a user could arrange; every `WHEN` = an action a user could take; every `THEN` = an outcome a user could see. FAIL a `WHEN` that is an invocation (a handler runs, a consumer receives, a job fires, data syncs) or a `THEN` asserting schema/type/nullability/call-count. Judge the BODY, never the story's title or ID. Never derive the story or scenario count from an architecture inventory (handlers, consumers, jobs) — that count moves when the system is re-architected though no business behavior changed, falsifying M5.
331
332> **M1 governs vocabulary; M7 governs subject matter.** A technical story in impeccably tech-free prose satisfies M1 while violating M7 — _"the system correctly synchronizes the record"_ names no framework and is still a technical case in a business costume. That gap is the most common way business specs rot. Ask what a user could SEE, not which words were used.
333
334> **[STOP — rework before emitting]** Reject and rework a story when ANY of these failure conditions holds:
335>
336> 1. Tech-specific prose — narrative/criteria name a framework, product, language type, or design-pattern class.
337> 2. Source code reference in prose — a class/method name, file path, or namespace appears outside an evidence carrier.
338> 3. Missing logical ID or evidence — no `FR-`/`BR-` ID, OR a requirement/rule with no `[Source: namespace/service/id]` abstract-anchor evidence (or explicit `TBD (pre-implementation)` marker).
339> 4. Vague acceptance criteria — non-testable, non-observable, or more than one valid interpretation.
340> 5. Not implementable from the artifact alone — a reader would have to read source or guess a rule, limit, role, or failure mode.
341> 6. Not demoable (M7) — a criterion's body fails the demo test: its `WHEN` is an invocation, or its `THEN` asserts schema/type/nullability/call-count, or no stakeholder-visible change answers _"what would they SEE?"_ — it is TECHNICAL-ONLY and belongs to the technical tree, not this story.
342
343---
344
345## Story Artifact Template
346
347````markdown
348---
349id: US-{YYMMDD}-{NNN}
350parent_pbi: '{PBI-ID}'
351title: '{Brief story title}'
352persona: '{User persona}'
353priority: P1 | P2 | P3
354story_points: 1 | 2 | 3 | 5 | 8 | 13
355complexity: Low | Medium | High | Very High
356man_days_traditional: '{ Xd (Yd code + Zd test) — from SP table }'
357man_days_ai: '{ Xd (Yd code + Zd test) — from SP table with AI }'
358sprint: 0 | 1 | 2 | ...
359status: draft | ready | in_progress | done
360module: '{ServiceA | ServiceB | ServiceC | ServiceD}'
361---
362
363# User Stories for {PBI Title}
364
365## Story 1: {Title}
366
367**As a** {user role}
368**I want** {goal}
369**So that** {benefit}
370
371### Acceptance Criteria
372
373#### Scenario 1: {Happy path title}
374
375```gherkin
376Given {context}
377When {action}
378Then {outcome}
379```
380
381#### Scenario 2: {Edge case title}
382
383```gherkin
384Given {edge state}
385When {action}
386Then {handling}
387```
388
389#### Scenario 3: {Error case title}
390
391```gherkin
392Given {context}
393When {invalid action}
394Then error "{message}"
395```
396
397---
398
399## Story 2: {Title}
400
401{Repeat structure...}
402
403---
404
405## Out of Scope
406
407- {Explicitly excluded items}
408
409## Story Dependencies
410
411| Story | Depends On | Type | Reason |
412| -------- | ---------- | ------------ | --------------------------------- |
413| US-{NNN} | - | independent | First slice, no dependencies |
414| US-{NNN} | US-{NNN} | must-after | Needs entity/API from prior story |
415| US-{NNN} | US-{NNN} | can-parallel | Independent feature slice |
416| US-{NNN} | US-{NNN} | blocked-by | Requires external service/infra |
417
418## Domain Context
419
420**Module:** {module}
421**Related Feature:** {feature doc path}
422**Entities:** {Entity1}, {Entity2}
423**Requirement IDs (M3 — inherited from PBI):** {FR-XXX / BR-XXX — primary citation spine}
424**Business Rules:** {BR-XXX references}
425**Evidence (secondary, stack-portable):** {`[Source: namespace/service/id]` abstract anchor per requirement, or `TBD (pre-implementation)`}
426
427## UI Wireframe
428
429### Layout
430
431{ASCII wireframe showing this story's UI slice — see UI wireframe protocol}
432
433### Components
434
435- **{ComponentName}** — {behavior for this story} _(tier: common | domain-shared | page/app)_
436
437> Classify per **Component Hierarchy** in `UI wireframe protocol` — search existing libs before proposing new components.
438
439### Interaction Flow
440
4411. User {action} on {component}
4422. System {response/feedback}
4433. UI updates to show {result}
444
445### States
446
447| State | Behavior |
448| ------- | -------------------------- |
449| Default | {what user sees initially} |
450| Loading | {spinner/skeleton} |
451| Empty | {empty state message} |
452| Error | {error handling} |
453
454> If backend-only: `## UI Wireframe` → `N/A — Backend-only change. No UI affected.`
455
456## Technical Notes
457
458- {Implementation hints if needed}
459
460## Validation Summary
461
462**Validated:** {date}
463
464### Confirmed
465
466- {decision}: {user choice}
467
468### Action Items
469
470- [ ] {follow-up if any}
471````
472
473---
474
475## Sprint 0 / Foundation Stories (Production Readiness)
476
477When the PBI includes a "Production Readiness Concerns" table with "Required" items, automatically generate Sprint 0 / foundation stories for each concern:
478
479| PBI Concern | Story Title | Story Points | Priority |
480| --------------------------------- | ------------------------------------------ | ------------ | --------- |
481| Code linting/analyzers = Required | "Set up code linting and formatting" | 1-2 SP | Must Have |
482| Error handling setup = Required | "Set up error handling foundation" | 2-3 SP | Must Have |
483| Loading indicators = Required | "Set up loading indicator infrastructure" | 1-2 SP | Must Have |
484| Docker integration = Required | "Set up Docker development environment" | 2-3 SP | Must Have |
485| CI/CD quality gates = Required | "Set up CI/CD quality gates" | 2-3 SP | Must Have |
486| Seed data = Required | "Set up seed data / data seeder" | 2-3 SP | Must Have |
487| Data migration = Required | "Create data migration for schema changes" | 1-3 SP | Must Have |
488
489### Rules
490
491- Foundation stories MUST ATTENTION be completed before feature stories begin
492- Mark as `sprint: 0` or `sprint: foundation` in story metadata
493- Each foundation story references the specific protocol section for implementation guidance
494- If PBI concern = "Existing", skip story generation (already set up)
495- If PBI concern = "No", skip story generation (explicitly opted out)
496
497---
498
499## Anti-Patterns to Avoid
500
501| Anti-Pattern | Problem | Correct Approach |
502| ------------------ | ------------------------------------------------- | --------------------------------------------- |
503| Horizontal slicing | "Backend story" + "Frontend story" = delays value | Vertical slice: thin end-to-end functionality |
504| Single scenario | Missing edge/error cases | Minimum 3 scenarios: happy, edge, error |
505| Vague criteria | "Fast", "user-friendly" untestable | Quantify: "< 200ms", "≤ 3 clicks" |
506| Solution-speak | "Use Redis cache" constrains team | Outcome: "Results return within 200ms" |
507| Effort >8 | Won't fit sprint, hard to estimate | Apply SPIDR, split until ≤8 |
508| No error scenario | Missing negative test coverage | Always include invalid input handling |
509| Generic persona | "As a user" too vague | Specific: "As a warehouse operator" |
510
511---
512
513## Key Rules
514
515- **Every story set MUST ATTENTION include a Story Dependencies table** — with types: `must-after`, `can-parallel`, `blocked-by`, `independent`. This enables `$prioritize` and `$plan` to respect implementation ordering.
516- **SPIDR splits MUST ATTENTION include dependency chains** — When splitting a story, declare which split stories depend on others.
517- **No orphan stories** — Every story must appear in the dependency table, even if independent.
518
519## Quality Checklist
520
521Before completing user stories:
522
523- [ ] Each story follows "As a... I want... So that..." format
524- [ ] SPIDR splitting applied (effort ≤8, prefer ≤5)
525- [ ] At least 3 scenarios per story: happy, edge, error
526- [ ] All scenarios use GIVEN/WHEN/THEN format
527- [ ] Effort estimated in Fibonacci (1, 2, 3, 5, 8)
528- [ ] Stories independent (can develop in any order)
529- [ ] Out of scope explicitly listed
530- [ ] Story Dependencies table included with all stories listed
531- [ ] Dependency types correct (must-after, can-parallel, blocked-by, independent)
532- [ ] Parent PBI linked in frontmatter
533- [ ] Domain vocabulary used correctly (if the project)
534- [ ] Authorization scenario included per story (unauthorized access rejection)
535- [ ] Seed data story included if PBI has seed data requirements
536- [ ] Data migration story included if PBI has schema changes
537- [ ] Validation interview completed
538
539---
540
541## Validation Step (MANDATORY)
542
543After creating user stories, validate with user.
544
545### Question Categories
546
547| Category | Example Question |
548| ---------------- | --------------------------------------------------- |
549| **Slicing** | "Are the story slices independent enough?" |
550| **Size** | "Any story >8 effort that needs further splitting?" |
551| **Scenarios** | "Any acceptance criteria missing for edge cases?" |
552| **Dependencies** | "Are there hidden dependencies between stories?" |
553| **Scope** | "Should anything be explicitly excluded?" |
554
555### Process
556
5571. Generate 2-4 questions focused on slicing quality, scenarios, and dependencies
5582. Use ask the user directly tool to interview
5593. Document in story artifact under `## Validation Summary`
5604. Update stories based on answers (split if needed)
561
562**This step is NOT optional.**
563
564---
565
566## Related
567
568| Type | Reference |
569| -------------- | --------------------------------------------------- |
570| **Role Skill** | `business-analyst` |
571| **Command** | `$story` |
572| **Input** | `$refine` output (PBI) |
573| **Next Steps** | `$spec [mode=tests]`, `$design-spec`, `$prioritize` |
574
575---
576
577## MANDATORY: Systematic Task Breakdown for Stories
578
579**MANDATORY IMPORTANT MUST ATTENTION** break down ALL stories into small, systematic todo tasks using task tracking BEFORE starting implementation. Each story MUST ATTENTION have its own set of tasks that cover:
580
5811. **Read & understand story** — Load story artifact, acceptance criteria, domain context
5822. **Identify vertical slice layers** — Backend entity/command/query, frontend component/store/API, integration points
5833. **Create implementation subtasks per layer** — One task per file or logical unit (entity, command handler, DTO, component, service, test)
5844. **Include spec tasks** — Each story MUST ATTENTION have corresponding test specifications (unit, integration, or E2E as appropriate)
5855. **Include validation task** — Verify story against acceptance criteria GIVEN/WHEN/THEN after implementation
5866. **Include review task** — Final quality check per story
587
588### Task Naming Convention
589
590```
591
592[Story US-{ID}] {Layer}: {Description}
593
594```
595
596Example for a "Create Invoice" story:
597
598```
599
600[Story US-001] Entity: Create Invoice entity with validation rules
601[Story US-001] Command: CreateInvoiceCommand + Handler
602[Story US-001] DTO: InvoiceDto with mapping
603[Story US-001] API: POST /api/invoices endpoint
604[Story US-001] Component: InvoiceCreateFormComponent
605[Story US-001] Store: InvoiceVmStore with create action
606[Story US-001] Test: Integration test for CreateInvoiceCommand
607[Story US-001] Test: E2E test for invoice creation flow
608[Story US-001] Review: Verify against AC scenarios
609
610```
611
612**Why:** Without systematic task breakdown, stories become monolithic — missed edge cases, incomplete specs, context loss during implementation.
613
614---
615
616## Next Steps
617
618**MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS** after completing this skill, you MUST ATTENTION use ask the user directly to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:
619
620- **"$spec [mode=tests] (Recommended)"** — Generate test specifications from stories
621- **"$pbi-mockup"** — Generate HTML mockup report from PBI and stories
622- **"$plan-validate"** — If stories need validation against plan
623- **"Skip, continue manually"** — user decides
624
625> **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.
626
627> **External Memory:** For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in `plans/reports/` — prevents context loss and serves as deliverable.
628
629> **Evidence Gate:** MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires `file:line` proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).
630
631<!-- SYNC:estimation-framework -->
632
633> **Estimation Framework** — Bottom-up first; SP DERIVED; output min-max range when likely ≥3d. Stack-agnostic. Baseline: 3-5yr dev, 6 productive hrs/day. AI estimate assumes Claude Code + project context.
634>
635> **Method:**
636>
637> 1. **Blast Radius pass** (below) — drives code AND test cost
638> 2. Decompose phases → hours/phase → `bottom_up_hours = Σ phase_hours`
639> 3. `likely_days = ceil(bottom_up_hours / 6) × productivity_factor`
640> 4. Sum **Risk Margin** (base + add-ons) → `max_days = likely_days × (1 + margin)`
641> 5. `min_days = likely_days × 0.9`
642> 6. Output as range when `likely_days ≥3`; single point allowed `<3` (still record margin)
643> 7. `man_days_ai` = same range × AI speedup
644> 8. `story_points` DERIVED from `likely_days` via SP-Days — NEVER driver. Disagreement >50% → trust bottom-up
645>
646> **Productivity factor:** 0.8 strong scaffolding+codegen+AI hooks · 1.0 mature default · 1.2 weak patterns · 1.5 greenfield
647>
648> **Cost Driver Heuristic (apply BEFORE work-type row):**
649>
650> - **UI dominates** in CRUD/business apps — 1.5-3x backend (states, validation, responsive, a11y, polish)
651> - **Backend dominates ONLY:** multi-aggregate invariants, cross-service contracts, schema migrations, heavy query/perf, new event flows
652>
653> **Reuse-vs-Create axis (PRIMARY lever, per layer):**
654>
655> | UI tier | Cost |
656> | -------------------------------------------- | -------- |
657> | Reuse component on existing screen | 0.1-0.3d |
658> | Add control/column to existing screen | 0.3-0.8d |
659> | Compose components into NEW screen | 1-2d |
660> | NEW screen, custom layout/states/validation | 2-4d |
661> | NEW shared/common component (themed, tested) | 3-6d+ |
662>
663> | Backend tier | Cost |
664> | ---------------------------------------------------- | --------- |
665> | Reuse query/handler from new place | 0.1-0.3d |
666> | Small update existing handler/entity | 0.3-0.8d |
667> | NEW query on existing repo/model | 0.5-1d |
668> | NEW command/handler on existing aggregate (additive) | 1-2d |
669> | NEW aggregate/entity (repo, validation, events) | 2-4d |
670> | NEW cross-service contract OR schema migration | 2-4d each |
671> | Multi-aggregate invariant / heavy domain rule | 3-5d |
672>
673> **Rule:** Sum tiers across UI+backend+tests, apply productivity factor. Reuse short-circuits tiers — call out.
674>
675> **Test-Scope drivers (compute test_count EXPLICITLY — "+tests" hand-wave is #1 failure):**
676>
677> | Driver | Count |
678> | --------------------------------- | ------------------------------------------------------ |
679> | Happy-path journeys | 1 per story / AC main flow |
680> | State-machine transitions | reachable transitions × allowed actors |
681> | Multi-entity state combos | state(A) × state(B) — REACHABLE only, not Cartesian |
682> | Authorization matrix | (owner, non-owner, elevated, unauth) × each mutation |
683> | Validation rules | 1 per required field / boundary / format / cross-field |
684> | UI states (per new screen/dialog) | happy, loading, empty, error, partial — present only |
685> | Negative paths / invariants | 1 per violatable business rule |
686>
687> | Test tier (Trad, incl. setup+assert+flake) | Cost |
688> | ------------------------------------------ | -------- |
689> | 1-5 cases, fixtures reused | 0.3-0.5d |
690> | 6-12 cases, 1 new fixture | 0.5-1d |
691> | 13-25 cases, multi-entity setup | 1-2d |
692> | 26-50 cases OR new state-machine coverage | 2-3d |
693> | >50 cases OR full E2E journey | 3-5d |
694>
695> **Test multipliers:** new fixture/seed harness +0.5d · cross-service/bus assertion +0.3d each · UI E2E ×1.5 · each new role +1-2 cases
696>
697> **Blast Radius (mandatory pre-pass — affects code AND test):**
698>
699> 1. Files/components directly modified — count
700> 2. Of those, "complex" (>500 LOC, multi-handler, central, frequently-modified) — count
701> 3. Downstream consumers (callers, event subscribers, cross-service) — list
702> 4. Shared/common code touched (multi-app blast) — yes/no
703> 5. Regression scope — areas needing re-test
704>
705> **Rule:** Complex touch → add `risk_factors`. Each downstream consumer → +1-3 regression cases. Blast >5 areas OR >2 complex → re-evaluate SPLIT before estimating.
706>
707> **Risk Margin (drives max bound):**
708>
709> | likely_days | Base margin |
710> | ------------------- | ------------------------------- |
711> | <1d trivial | +10% |
712> | 1-2d small additive | +20% |
713> | 3-4d real feature | +35% |
714> | 5-7d large | +50% |
715> | 8-10d very large | +75% |
716> | >10d | +100% AND **flag SHOULD SPLIT** |
717>
718> **Risk-factor add-ons (additive — enumerate in `risk_factors`):**
719>
720> | Factor | +margin |
721> | --------------------------------------------------------------------- | ------- |
722> | `touches-complex-existing-feature` (>500 LOC, multi-handler, central) | +20% |
723> | `cross-service-contract` change | +25% |
724> | `schema-migration-on-populated-data` | +25% |
725> | `new-tech-or-unfamiliar-pattern` | +30% |
726> | `regression-fan-out` (≥3 downstream areas re-test) | +20% |
727> | `performance-or-latency-critical` | +20% |
728> | `concurrency-race-event-ordering` | +25% |
729> | `shared-common-code` (multi-consumer/multi-app) | +25% |
730> | `unclear-requirements-or-design` | +30% |
731>
732> **Collapse rule:** total margin >100% → STOP, split (padding past 2x is dishonesty). Margin <15% on `likely_days ≥5` → under-estimated, widen.
733>
734> **Work-Type Caps (hard ceilings on `likely_days`):**
735> | Work type | Max SP | Max likely |
736> | --- | --- | --- |
737> | Single field / config flag / style fix | 1 | 0.5d |
738> | Add property to existing model + bind to existing UI | 2 | 1d |
739> | **Additive endpoint + minor UI control** (button/menu/column), reuses fixtures | **3** | **2-3d** |
740> | Additive endpoint + **NEW UI surface** OR additive multi-layer + new domain rule + 2+ test files | 5 | 3-5d |
741> | NEW model/aggregate OR migration OR cross-module contract OR heavy test (>1.5d) OR NEW UI + non-trivial backend | 8 | 5-7d |
742> | NEW UI surface + (NEW aggregate OR migration OR cross-service contract) | 13 | SHOULD split |
743> | Cross-service contract + migration combined | 13 | SHOULD split |
744> | Beyond | 21 | MUST split |
745>
746> **SP→Days (validation only):** 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d (Trad/AI likely)
747> **AI speedup:** SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x. AI cost = `(code_gen × 1.3) + (test_gen × 1.3)` (30% review overhead).
748>
749> **MANDATORY frontmatter:**
750>
751> ```yaml
752> story_points: <n>
753> complexity: low | medium | high | critical
754> man_days_traditional: '<min>-<max>d' # range when likely ≥3d; '<N>d' when <3d
755> man_days_ai: '<min>-<max>d'
756> risk_margin_pct: <n> # base + add-ons
757> risk_factors: [touches-complex-existing-feature, regression-fan-out] # closed-list from add-ons; [] if none
758> blast_radius:
759> touched_areas: <n>
760> complex_touched: <n>
761> downstream_consumers: [list or count]
762> shared_common_code: yes | no
763> estimate_scope_included: [code, integration-tests, frontend, i18n, docs]
764> estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds]
765> estimate_reasoning: |
766> 5-7 lines covering:
767> (a) UI tier — row applied
768> (b) Backend tier — row applied
769> (c) Test scope — case breakdown by driver, file count, fixtures, tier row
770> (d) Cost driver — dominant tier + why
771> (e) Blast radius — touched, complex, regression scope
772> (f) Risk factors — list driving margin; why not larger/smaller
773> Example: "UI: compose Form/Table/Dialog → NEW screen (~1.5d). Backend: NEW command on existing aggregate,
774> reuses validation+repo (~1d). Tests: 4 transitions × 2 actors + 3 validation + 2 UI states = 13 cases,
775> 1 new fixture → tier 13-25 ~1.5d. Driver: UI composition + new states. Blast: 4 areas, 1 complex.
776> Risk: base 35% + touches-complex +20% = 55% → max 3.9d → range 2.5-4d."
777> ```
778>
779> **Sanity self-check:**
780>
781> - `likely_days ≥3d` and single-point? → reject, must be range
782> - Margin <15% on `likely_days ≥5d`? → under-estimated, widen
783> - Margin >100%? → STOP, split instead of buffer
784> - Complex existing feature touched, no regression budget in `(c)`? → reject
785> - Blast `>5` areas OR `>2` complex, no split discussion? → reject
786> - Purely additive on existing model AND existing UI? → cap SP 3 unless tests >1.5d
787> - NEW UI surface (page/complex form/dashboard)? → SP 5+ even if backend one endpoint
788> - Backend cross-service / migration / multi-aggregate? → SP 8+ regardless of UI
789> - `bottom_up_hours / 6` vs SP-Days disagreement >50%? → trust bottom-up, downgrade SP
790> - Without tests, SP drops ≥1 bucket? → tests dominate; state explicitly
791> - Reasoning called out UI vs backend vs blast vs risk factors? → if missing, add
792
793<!-- /SYNC:estimation-framework -->
794
795<!-- SYNC:ui-system-context -->
796
797> **UI System Context** — For ANY task touching `.ts`, `.html`, `.scss`, or `.css` files:
798>
799> **MUST ATTENTION READ before implementing:**
800>
801> 1. `docs/project-reference/frontend-patterns-reference.md` — component base classes, stores, forms
802> 2. `docs/project-reference/scss-styling-guide.md` — BEM methodology, SCSS variables, mixins, responsive
803> 3. `docs/project-reference/design-system/README.md` — design tokens, component inventory, icons
804>
805> Reference `docs/project-config.json` for project-specific paths.
806
807<!-- /SYNC:ui-system-context -->
808
809<!-- SYNC:ui-wireframe -->
810
811> **UI Wireframe** — Process visual design input (Figma URLs, screenshots, wireframes) via appropriate tool BEFORE creating wireframes. Use box-drawing ASCII characters for spatial layout. Classify every component into exactly ONE tier: Common (cross-app reusable) / Domain-Shared (cross-domain) / Page (single-page). Duplicate UI code = wrong tier. Search existing component libraries before creating new (>=80% match = reuse). Detail level varies by skill (idea=rough, story=full decomposition).
812
813<!-- /SYNC:ui-wireframe -->
814
815<!-- SYNC:critical-thinking-mindset -->
816
817> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
818> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
819
820<!-- /SYNC:critical-thinking-mindset -->
821
822<!-- SYNC:sequential-thinking-protocol -->
823
824> **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.
825>
826> **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.
827>
828> **Format (explicit mode — visible thought trail):**
829>
830> 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty
831> 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact
832> 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale
833> 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting
834> 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80%
835>
836> **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.
837>
838> **Stop conditions:** confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.
839>
840> **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).
841>
842> **Deep-dive:** see `$sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).
843
844<!-- /SYNC:sequential-thinking-protocol -->
845
846<!-- SYNC:ai-mistake-prevention -->
847
848> **AI Mistake Prevention** — Failure modes to avoid on every task:
849>
850> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
851> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
852> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
853> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
854> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.
855> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
856> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.
857> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
858> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
859
860<!-- /SYNC:ai-mistake-prevention -->
861
862<!-- SYNC:estimation-framework:reminder -->
863
864- **MANDATORY MUST ATTENTION** estimation: bottom-up phase hours drive `man_days_traditional` (`Σh/6 × productivity_factor`); SP DERIVED. UI cost usually dominates — bump SP one bucket if NEW UI surface (page/complex form/dashboard). Frontmatter MUST include `story_points`, `complexity`, `man_days_traditional`, `man_days_ai`, `estimate_scope_included`, `estimate_scope_excluded`, `estimate_reasoning` (UI vs backend cost driver). Cap SP 3 for additive-on-existing-model+existing-UI unless test scope >1.5d. SP 13 SHOULD split, SP 21 MUST split.
865 <!-- /SYNC:estimation-framework:reminder -->
866
867<!-- SYNC:ui-system-context:reminder -->
868
869**IMPORTANT MUST ATTENTION** read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change.
870
871<!-- /SYNC:ui-system-context:reminder -->
872
873<!-- SYNC:critical-thinking-mindset:reminder -->
874
875**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
876
877<!-- /SYNC:critical-thinking-mindset:reminder -->
878
879<!-- SYNC:sequential-thinking-protocol:reminder -->
880
881**MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `$sequential-thinking` skill.
882
883<!-- /SYNC:sequential-thinking-protocol:reminder -->
884
885<!-- SYNC:ai-mistake-prevention:reminder -->
886
887**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
888
889<!-- /SYNC:ai-mistake-prevention:reminder -->
890
891<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->
892
893## Prompt-Enhance Closing Anchors
894
895**IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
896**IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution
897**IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence
898**IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
899
900<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->
901
902<!-- SYNC:project-protocol-overlay -->
903
904> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.
905>
906> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.
907
908<!-- /SYNC:project-protocol-overlay -->
909
910<!-- SYNC:project-protocol-overlay:reminder -->
911
912**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.
913
914<!-- /SYNC:project-protocol-overlay:reminder -->
915
916## Closing Reminders
917
918**IMPORTANT MUST ATTENTION Goal:** produce sprint-ready, INVEST-valid user stories — tech-agnostic, testable GWT criteria, evidence-cited estimates, dependency-mapped — that a team with zero codebase knowledge can implement on any stack.
919
920**IMPORTANT MUST ATTENTION Main steps (execute in order, NEVER skip):** read PBI + active plan + domain context → identify VERTICAL slices → SPIDR-split (SP >8 MUST / >5 SHOULD) → write INVEST stories with min 3 GWT + 1 auth scenario → estimate bottom-up (Blast-Radius pre-pass, SP DERIVED) + full frontmatter → emit Story Dependencies table (no orphans) → MANDATORY ask the user directly validation → save to `team-artifacts/pbis/stories/` → suggest `$spec [mode=tests]`.
921
922**Protocols in force (concise digest of the SYNC/shared blocks this skill carries) — MUST ATTENTION honor each canonical body, NEVER skip one:**
923
924- **Estimation Framework:** Bottom-up phase hours drive man-days; SP DERIVED; UI usually dominates.
925- **UI System Context:** Read frontend-patterns, scss-styling, design-system before any UI change.
926- **UI Wireframe:** Box-ASCII layout; classify each component into one tier; reuse before new.
927- **Critical Thinking:** Trace proof for every claim; confidence >80% to act.
928- **Sequential Thinking:** Multi-step Thought N/M with revision/branch/hypothesis markers; confidence closer.
929- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
930
931**IMPORTANT MUST ATTENTION** every story MUST satisfy AI-SDD mandates M1-M5 and M7 — tech-agnostic prose, `FR-`/`BR-` logical ID + `[Source: namespace/service/id]` abstract anchor (NEVER `file:line` in story prose), testable GWT criteria, rebuild-from-scratch, demoable business outcomes — reject and rework on any STOP condition — why: stories drive implementation on any stack, so a leaked framework/class name breaks portability.
932**IMPORTANT MUST ATTENTION** apply the M7 demo test to every criterion's BODY — _"what would a stakeholder SEE change?"_; no answer → TECHNICAL-ONLY, drop it. FAIL a `WHEN` that is an invocation (handler runs, consumer receives, job fires, data syncs) or a `THEN` asserting schema/type/nullability/call-count; NEVER derive the story/scenario count from an architecture inventory — why: M1 governs vocabulary, M7 governs subject matter — a technical story in tech-free prose passes M1 and still rots the business tree.
933**IMPORTANT MUST ATTENTION** every story set includes a Story Dependencies table with no orphan stories; SP >8 MUST split, >5 SHOULD split via SPIDR — why: ordering feeds `$prioritize` and `$plan` and oversized stories miss the sprint.
934**MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using task tracking BEFORE starting; mark one `in_progress` and `completed` immediately — why: long story files exhaust context and lose findings without external tracking.
935**MANDATORY IMPORTANT MUST ATTENTION** estimation is bottom-up — phase hours drive `man_days_traditional` (`Σh/6 × productivity_factor`), SP DERIVED never the driver; run the Blast Radius pre-pass and compute `test_count` explicitly per driver — NEVER hand-wave "+tests" (the #1 failure) — why: SP-first estimates anchor to a guess, not the work.
936**MANDATORY IMPORTANT MUST ATTENTION** emit the full estimate frontmatter — `story_points`, `complexity`, `man_days_traditional`, `man_days_ai`, `risk_margin_pct`, `risk_factors`, `blast_radius`, `estimate_scope_*`, `estimate_reasoning` (UI vs backend cost driver) — why: downstream `$prioritize` and `$plan` read these fields, blanks block them.
937**MANDATORY IMPORTANT MUST ATTENTION** write min 3 GWT scenarios (happy + edge + error) PLUS a mandatory authorization scenario per story; every criterion has exactly ONE observable interpretation — why: a vague or single-scenario story ships untested edge/error/auth paths.
938**MANDATORY IMPORTANT MUST ATTENTION** slice VERTICALLY (thin end-to-end), NEVER horizontally (backend/frontend split) — why: horizontal slices delay deliverable user value.
939**MANDATORY IMPORTANT MUST ATTENTION** search existing component libraries and domain vocabulary BEFORE proposing new components/entities (>=80% match = reuse); use the project's own entity names — why: duplicate UI/domain code = wrong tier and fragments the codebase.
940**MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` (or grep/graph) evidence with a confidence % for every claim about existing code/entities — >80% to act, <80% verify first — why: AI hallucinates entity/API names; unverified scoping mis-slices the story.
941**MANDATORY IMPORTANT MUST ATTENTION** validate stories with the user by asking the user directly before handoff — NEVER auto-decide slicing/scope/effort — why: silent assumptions on ambiguous scope ship the wrong stories.
942**MANDATORY IMPORTANT MUST ATTENTION** add a final review todo task to verify every story against its AC scenarios, the dependency table, and the Quality Checklist.
943
944**Anti-Rationalization:**
945
946| Evasion | Rebuttal |
947| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
948| "Story is small, skip SPIDR/estimate" | SP >8 MUST split, >5 SHOULD — and SP is DERIVED from bottom-up hours, not eyeballed. Estimate. |
949| "Tech notes need the class name" | Source identifiers belong only in evidence carriers as `[Source: namespace/service/id]` — never in prose (M1/M2). |
950| "Happy path is enough" | Min 3 scenarios + a mandatory authorization scenario per story. Edge + error + auth are NOT optional. |
951| "+tests covers the test cost" | Compute `test_count` explicitly per driver (auth matrix, validation, states). Hand-wave is the #1 estimate failure. |
952| "Independent story, skip the dep table" | No orphan stories — every story appears in the dependency table, even if `independent`. |
953| "Slicing is obvious, skip validation" | ask the user directly validation is MANDATORY, not optional. The user confirms slicing/scope/effort. |
954
955**IMPORTANT MUST ATTENTION** AI-SDD M1-M5/M7 (tech-agnostic + demoable) + dependency table + bottom-up estimate are the three rules this skill must never skip — re-anchored here (recency) and in the Quick Summary (primacy).
956
957**MANDATORY IMPORTANT MUST ATTENTION** READ the project-reference docs named in the Quick Summary blockquote BEFORE starting — `project-structure-reference.md`, `docs/project-reference/domain-entities-reference.md` (business entities/models), `docs/specs/` (existing TCs for related features) — plus the Frontend/UI Context docs when the PBI touches UI. File not found → search for the project's documentation, coding standards, and architecture docs instead — why: story scoping that guesses at entity names and module structure mis-slices the work.
958
959**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking.
960
961> **[IMPORTANT]** Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.
962
963<!-- CODEX:SYNC-PROMPT-PROTOCOLS:START -->
964
965## Hookless Prompt Protocol Mirror (Auto-Synced)
966
967Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs`
968
969## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.
970
971**Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=<key>`) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available.
972
9731. **DETECT:** If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list.
9742. **ANALYZE:** Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination.
9753. **AUTO-SELECT:** Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow.
9764. **ACTIVATE:** For a selected workflow, call `$start-workflow <workflowId>`; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task.
9775. **CREATE TASKS:** task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps.
9786. **PARALLELIZE:** Before executing the task list, tag each task `PAR` (independent inputs + write set disjoint from every other `PAR` task) or `SEQ` (name the blocking dependency), group `PAR` tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates.
9797. **EXECUTE:** Advance per the **Workflow Step Advancement & Parallel Phases** rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it)
980
981## Shared AI-SDD Protocol Markers
982
983Source: `.claude/skills/shared/sync-inline-versions.md`
984
985## SYNC:ai-sdd-artifact-contract
986
987> **AI-SDD Artifact Contract** — Shared spec-driven development rules stay portable and source-owned.
988>
989> 1. Keep reusable AI-SDD principles in `.claude`; put repository-specific paths, commands, owners, products, and formats in project config/reference docs.
990> 2. Preserve cycle: `spec -> plan -> tasks -> implement -> verify -> update spec/docs`.
991> 3. Trace every requirement or invariant through decision, task, TC/test, source evidence, and docs/spec update.
992> 4. Treat code-to-spec extraction as reference-only until accepted by the canonical spec owner.
993> 5. Any supported AI tool may plan, implement, review, or verify with synced context; using multiple tools is optional.
994> 6. Update `.claude` source first, then sync generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. — why: mirrors are generated artifacts; hand-edits are overwritten on the next sync
995> 7. If `docs/project-config.json`, root instruction files, or a required project-reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work.
996>
997> **Active reference:** `shared/sdd-artifact-contract.md` in the active skills root.
998
999---
1000
1001## SYNC:ai-sdd-artifact-contract:reminder
1002
1003- **MANDATORY** Apply `shared/sdd-artifact-contract.md`; keep reusable AI-SDD in `.claude` and local rules in project docs.
1004- **MANDATORY** Code-to-spec extraction is reference-only until canonical acceptance; any supported AI tool may execute with synced context.
1005- **MANDATORY** Update `.claude` source before syncing generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`.
1006- **MANDATORY** Missing or stale project config, root instruction files, or required reference docs route project-specific work through `$project-init` or the narrow setup route automatically.
1007 **[TASK-PLANNING] [MANDATORY]** BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes.
1008
1009## [LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip.
1010
1011Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned".
1012
1013**Extract lessons — ROOT CAUSE ONLY, not symptom fixes:**
1014
10151. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value".
10162. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up.
10173. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase.
10184. Consolidate: multiple mistakes sharing one failure mode → ONE lesson.
10195. **Recurrence gate:** "Would this recur in future session WITHOUT this reminder?" — No → skip `$learn`.
10206. **Auto-fix gate:** "Could `$code-review`/`$code-simplifier`/`$security-review`/`$lint` catch this?" — Yes → improve review skill instead.
10217. BOTH gates pass → ask user to run `$learn`.
1022 **[CRITICAL-THINKING-MINDSET]** Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
1023 **Anti-hallucination principle:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
1024 **AI Attention principle (Primacy-Recency):** Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows.
1025 **Goal-driven execution:** Define success criteria first, loop until verified, and stop only when observable checks pass.
1026 **Tests verify intent:** Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior.
1027
1028## Common AI Mistake Prevention (System Lessons)
1029
1030- **Re-read files after context compaction.** Edit requires prior Read in same context; compaction wipes read state. Re-read before editing.
1031- **Grep for old terms after bulk replacements.** AI over-trusts find/replace completeness. Grep full repo after bulk edits for missed refs in docs/configs/catalogs.
1032- **Check downstream references before deleting.** Deletions cascade doc/code staleness. Map referencing files before removal.
1033- **After memory loss, check existing state before creating new.** Compaction wipes prior-work memory. Query current state to resume — never blindly duplicate.
1034- **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, method signatures. Grep to confirm existence before documenting/referencing.
1035- **Trace full dependency chain after edits.** Changing a definition misses downstream consumers. Trace the full chain.
1036- **When renaming, grep ALL consumer file types.** Some file types silently ignore missing refs (no compile error). Search code, templates, configs, generated files.
1037- **Trace ALL code paths when verifying correctness.** Code existing ≠ code executing. Trace early exits, error branches, conditional skips — not just happy path.
1038- **Update docs that embed canonical data when source changes.** Docs inlining derived data (workflows, schemas, configs) go stale silently. Update all embedding docs alongside source.
1039- **Verify sub-agent results after context recovery.** Background agents may finish while parent compacted — grep-verify output, don't trust assumed completion.
1040- **Cross-check full target list against sub-agent assignments.** Parallel sub-agents by category miss boundary items. Reconcile union of assignments against target list before proceeding.
1041- **Sub-agents inherit knowledge only from their agent .md definition — use custom agent types, not built-in Explore.** Tool adoption = permission + knowledge + enforcement (numbered workflow step).
1042- **Persist sub-agent findings incrementally, not as a final batch.** Long sub-agents hit cutoffs before final write — findings lost. Instruct append-per-section to report file.
1043- **When debugging, ask "whose responsibility?" before fixing.** Trace caller (wrong data) vs callee (wrong handling). Fix at responsible layer — never patch symptom site.
1044- **Test failure → record a provisional verdict before trace/edit, then investigate.** Use the full five-way taxonomy: SOURCE-WRONG (production violates intent), TEST-WRONG (assertion/setup is stale), TEST-NOT-OPTIMAL (valid but fragile or low-signal test), ENVIRONMENT-BLOCKED (external state prevents a verdict), or AMBIGUOUS (intent/evidence cannot choose safely). Then trace root cause and triangulate against the governing spec (`docs/specs/**` if one exists) AND source. NEVER weaken an assertion, add a skip, relax a timeout, or change source merely to force green.
1045- **Grep ALL removed names after extraction/refactoring.** Primary file "done" ≠ secondary files clean. Grep entire scope for every removed symbol before declaring complete.
1046- **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Pattern-matching as "wrong" skips context. Before changing or reporting any constant/limit/flag/cutoff: read comments, git blame, the CALLER's ordering (the guarantee that makes the value correct usually lives in code running immediately BEFORE the cited line), and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard — and in a validation pass, an accurate `file:line` citation proves the transcription, never the defect.
1047- **Verify ALL affected outputs, not just the first.** One build green ≠ all green. Multi-stack changes (backend/frontend/tests/docs) require verifying EVERY output.
1048- **Evaluate fit before copying a nearby pattern.** Closest example ≠ matching preconditions — verify the new context shares the same constraints, base classes, scope, lifetime.
1049- **Holistic-first debugging — resist nearest-attention trap.** Don't dive into first plausible cause. List EVERY precondition (config, env vars, paths, DB, endpoints, creds, versions, DI, data). Verify each against evidence (grep/query — not reasoning). Ask "what would falsify this?" — if nothing, it's not a hypothesis. Most expensive failure: going deeper in "obvious" layer while bug sits in layer never questioned.
1050- **Surgical changes — apply the diff test (context-aware).** Two modes: (1) Bug fix → every line traces to the bug; no restyling; orphan cleanup only for imports YOUR changes made unused. (2) Review/enhancement → implement improvements AND announce as "Enhancement beyond main request: [what]". Never silently scope-creep. Diff test: "Would this line exist if I wasn't asked to do X?" — if no, delete or announce.
1051- **Surface ambiguity before coding — don't pick silently.** Multiple valid interpretations → present each with effort: "[Request] could mean (1) [N h], (2) [N h]. Which matters?" List scope/format/volume/constraints assumptions first. If simpler path exists, say so. Never silently pick.
1052- **[MANDATORY FIRST ACTION] ALWAYS activate a suitable skill or workflow BEFORE responding.** Match task against workflow catalog + skill list; invoke via skill invocation or `$start-workflow <workflowId>`. NEVER answer or write code before checking. Skip = protocol violation.
1053- **Why-Review adversarial mindset — apply when reviewing any plan, decision, or design.** Default SKEPTIC not VALIDATOR: steel-man a rejected alternative, invert each stated reason ("what does it sacrifice?"), stress-test top 2-3 assumptions, run pre-mortem ("ships, fails in 3 months — what breaks?"), surface 1-2 alternatives author missed. Section presence ≠ quality; quality = causal reasoning + concrete mitigations + evidence, not "it's better" or "monitor closely".
1054- **Front-load report-write in sub-agent prompts for large reviews.** Many-file sub-agents hit budget before final write — findings lost. Design prompts so: (1) report-write is first explicit deliverable, (2) append per-file/section (not batched), (3) scope bounded so reads don't exhaust budget. Truncated mid-sentence with no report file → spawn narrower scope, don't retry same prompt.
1055- **After context compaction, re-verify all prior phase outcomes before continuing.** Summaries describe intent, not environment state (git index, filesystem, processes). On resume, FIRST audit: git status, re-read modified files, verify filesystem. Every "completed" claim is an untested hypothesis until evidence confirms.
1056- **OOM/memory: check row count before row size.** Triage: (1) Unbounded query — no DB filter for trigger? Push filter to DB; eliminates OOM. (2) Large rows? Projection reduces proportionally. Row reduction > projection in ROI.
1057- **Assert the outcome your system OWNS, never the intermediate state your INFRASTRUCTURE owns.** When testing anything asynchronous (queue/broker delivery, retries, background jobs, caches, replication), assert the final business/entity state. NEVER assert the delivery bookkeeping — consume/send status, attempt counts, last-error, row existence or counts in a broker, scheduler, or outbox/inbox table. That bookkeeping lives in shared infrastructure that ANY co-running process (a peer worker, a second replica, a leftover local container) can write, usually under a deterministic shared key, so the assertion silently tests the developer's environment instead of the system: green when run alone, flaky the instant anything else shares that broker + database. Gate question for every assertion: "would this hold no matter WHICH process did the work?" — if no, assert the converged data state instead. Corollary: process-local fault injection and in-process telemetry cannot gate work any process may perform — use them as stress amplifiers (arm → bounded window → disarm → assert convergence), never as preconditions.
1058- **Keep domain concepts out of generic/shared/infrastructure layers.** Reusable layer (shared library, framework, infra module) must reference NO consumer-specific domain concept — tenant/customer/product IDs, business entities, feature rules. Leak compiles + runs → passes review silently while coupling the "reusable" layer to one consumer. Keep shared type domain-free; push domain fields/logic down into the consumer via subclass/composition. — why: a layer coupled to one consumer's domain is no longer reusable.
1059
1060<!-- CODEX:SYNC-PROMPT-PROTOCOLS:END -->