@pavp/storywright 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,196 +1,321 @@
1
1
  ---
2
2
  name: story-split
3
- description: Detect when a story is too big to ship in one sprint and propose an INVEST-driven split into an epic with sub-stories. Never auto-splits — always proposes, then waits for user confirmation.
3
+ description: Split an oversize story into an epic plus Cohn+Gherkin children. Mechanical NxN dep matrix and per-child V audit. Asks ONLY in terminal. Never auto-splits.
4
4
  trigger: "/story-split | split this story | divide this story | dividir historia | this is too big"
5
- intent: Splitting skill that uses the INVEST failure reasons (from invest-checklist) as the rationale for decomposition. Produces an epic skeleton plus N child story stubs, ready to feed back into story-generate.
6
- version: 1.0.0
5
+ intent: Splitting skill driven by INVEST failure reasons. Produces an epic plus N child story stubs in the v2.2 canonical Cohn+Gherkin shape, with mechanical dependency matrix and Valuable audit per child.
6
+ version: 2.2.0
7
7
  inputs:
8
8
  - text
9
9
  - image
10
10
  - figma-link
11
11
  outputs:
12
- - split-plan.md
13
12
  - epic.md
14
- - story-1.md, story-2.md, ... (N child stubs)
13
+ - story-1.md
14
+ - story-2.md
15
+ - .storywright-context.json
15
16
  composes:
16
17
  - _components/invest-checklist
17
18
  - _components/clarification-questions
19
+ - _components/acceptance-criteria
20
+ - _components/jira-wiki-formatter
18
21
  ---
19
22
 
20
23
  ## Purpose
21
24
 
22
- When a story is an epic in disguise, splitting badly is worse than not splitting. This skill uses **established INVEST-compatible patterns** (workflow steps, business rules, user roles, data variations, happy/sad paths, simple/complex) to propose a clean decomposition. The user always approves the plan before any child stories are written.
25
+ When a story is an epic in disguise, splitting badly is worse than not splitting. This skill uses established INVEST-compatible patterns to propose a clean decomposition, then mechanically verifies each child's independence and value before saving. The user always approves the plan before any child is written.
23
26
 
24
- ## When to use
27
+ ## Hard rules (v2.2 parity with refine/generate)
25
28
 
26
- - `[[invest-checklist]]` returned `SPLIT RECOMMENDED` (failures on I, E, or S).
27
- - User explicitly asks: "this story is too big, split it".
28
- - Input visibly mixes ≥2 flows.
29
+ 1. **Terminal-only clarifications.** Never write any sidecar question file. All gap questions through `AskUserQuestion`, batched ≤4. Non-blocking gaps `⚠️ Assumed` inline.
29
30
 
30
- ## Inputs & interpretation
31
+ 2. **Children are Cohn+Gherkin canonical.** Each child has ONE Use Case block + ONE AC scenario (one Given chain + one `When` + one `Then`). If a child still needs >1 `When`/`Then` → recursive re-split.
31
32
 
32
- - **text**the oversize story (or a one-line goal that's clearly epic-scoped).
33
- - **image (optional)** — companion mockup. Use to validate scope and reveal hidden sub-flows the text doesn't mention.
34
- - **figma-link (optional)** — companion design. Often makes splitting easier: prototype links and frame structure reveal natural flow boundaries that map to children.
33
+ 3. **No mini-PRDs in children.** Same prohibition list as refine v2.2 no NFR blocks, no Edge Cases enumerations, no Dependencies prose, no per-claim visual specs, refinement logs ≤3 lines (≤5 if recursive split).
35
34
 
36
- ### Mixed inputs
35
+ 4. **Output language matches the user's chat language.** Auto-detect via rule 4a; ask only if signals split. Persist via rule 9.
37
36
 
38
- When the user provides text + image / Figma alongside the story:
39
- - **Text is canonical for User Story / Scope / Business Goal** of the epic.
40
- - **Figma / image is canonical for flow structure** — use prototype links to enumerate candidate sub-flows. Each flow is a candidate child story.
41
- - **Conflict handling:** if Figma shows N flows but text only mentions K (K < N), surface this in the gap-check via `[[clarification-questions]]` BEFORE drafting the split plan. Ask: "Figma includes flows for X, Y, Z — include in this epic, or scope out?" Never silently expand or shrink scope.
42
- - See `[[story-generate]]` "Mixed inputs" for the full source-priority matrix.
37
+ 5. **Visual inference confidence single banner only** in each child's Design Reference block. No per-claim `[mockup-pixel-derived]` tags.
43
38
 
44
- ## Application (step-by-step)
39
+ 6. **Sibling task IDs.** When referencing tickets that don't exist yet, follow rule F (naming pattern) instead of inventing slugs.
40
+
41
+ 7. **Chrome detection — closed list** (nav rail, top bar, footer, toast slot, modal scrim, app tabs). If image shows chrome and the input doesn't mention it, ask whether to add as its own child, attach to an existing child, or scope out.
42
+
43
+ 8. **Anti-PRD is part of each child's INVEST `Small` criterion** — see `[[invest-checklist]]` Small.
44
+
45
+ 9. **Cross-skill context persistence.** Read `<output-folder>/.storywright-context.json` first (exact folder only). Write updated answers back at the end. Schema:
46
+ ```json
47
+ {
48
+ "version": 1,
49
+ "decided_at": "<ISO date>",
50
+ "decided_by_skill": "story-split",
51
+ "language": "EN | ES | ...",
52
+ "chrome_scope": "in-scope | in-scope-placeholder | sibling | out-of-scope",
53
+ "siblings": "TODO | <list of IDs> | not-applicable",
54
+ "design_source": "raster | figma | tokens",
55
+ "naming_pattern": "<see rule F>",
56
+ "extra": { "split_pattern": "...", "core_complexity": "..." }
57
+ }
58
+ ```
45
59
 
46
- ### Pre-split gateSTOP conditions
60
+ 10. **Children independencemechanical detection (A).** For each child Cj, parse its `Given:` lines for surface nouns owned by sibling Ci. If matched → `DEP(Cj → Ci)`. The dependency matrix IS the union of those matches. No intuition-based deps. Affected child's INVEST `Independent` becomes `PARTIAL · depends on <Ci>`. Build order in epic.md is a topological sort of the matrix.
47
61
 
48
- Before splitting anything, run `[[invest-checklist]]` and apply these gates:
62
+ 11. **Per-child V audit (C).** For each candidate child, run one-line test: "If only this child ships and no sibling exists, does a real user complete a real task?". If answer is "no, useless until <other> ships" → mark V = `WEAK · merge-upstream-candidate` and recommend merging into the parent surface. Do not let stylistic/UI-fragment children survive the split.
49
63
 
50
- - **Valuable FAILS** **STOP. Do not split.** A non-valuable item is a technical task, not a story. Combine it with related user-facing work; don't decompose it.
51
- - **Testable FAILS** → **fix in place** via `[[story-refine]]` first. Splitting an untestable story produces untestable children.
52
- - **Negotiable FAILS** → fix in place; the story is over-prescriptive, not too big.
53
- - **Estimable FAILS due to unknowns** → run a **spike** (Pattern 9 below), not a split.
54
- - **Independent / Estimable / Small FAIL** → continue to pattern selection.
64
+ 12. **Passive-goal downstream prompt (G).** If any child's `I want to` verb is observational (view/see/read/browse/look/inspect/monitor) AND `so that` lacks a follow-up action ask once via `AskUserQuestion` per child (batched ≤4 across children).
55
65
 
56
- ### Pattern catalog (apply in order; stop at first that fits)
66
+ 13. **Determinism on counts.** Use the same deterministic surface-vs-styling counter (rule D from refine v2.2) inside child re-split checks.
57
67
 
58
- Based on the Humanizing Work splitting methodology (Richard Lawrence & Peter Green).
68
+ ### 4a. Language auto-detect expanded signals (E)
69
+ Same weighted signal table as refine v2.2 (Gherkin keywords, persona phrasing, column names, domain verbs, title). Adopt silently when high+medium signals agree; ask only if split.
59
70
 
60
- 1. **Workflow stepsthin end-to-end slices.**
61
- **Critical:** this is NOT "step 1 / step 2 / step 3" of the journey. Each child must deliver the **full** workflow with increasing sophistication.
62
- - ❌ Wrong: Story 1 = editorial review, Story 2 = legal approval, Story 3 = publish. (Story 1 alone delivers nothing observable to the user.)
63
- - Right: Story 1 = publish post immediately, no reviews. Story 2 = add editorial review step. Story 3 = add legal step. Each story produces visible behavior.
71
+ ### Rule F. Naming patternask once, persist
72
+ Same kebab / verb-noun / domain-action / Jira-prefix options. Persist in `naming_pattern`. Reuse across this run AND future skills.
73
+
74
+ ### Rule D. Surface vs styling (deterministic)
75
+ A noun counts as a separate surface ONLY if it has its own user goal (verb). Styling, sub-components, and passive layout assertions do not count.
76
+
77
+ ## When to use
78
+
79
+ - `[[invest-checklist]]` returned `SPLIT RECOMMENDED` (I, E, or S fail).
80
+ - User explicitly asks: "this story is too big, split it".
81
+ - `[[story-refine]]` or `[[story-generate]]` deterministic pre-split test ≥2.
82
+
83
+ ## Inputs & interpretation
64
84
 
65
- 2. **CRUD operations.** When the input says "manage" / "handle" / "maintain", it bundles operations. Split into Create / Read / Update / Delete.
85
+ - **text** the oversize story (or epic-scoped one-liner).
86
+ - **image (optional)** — companion mockup. Use to validate scope and reveal hidden sub-flows.
87
+ - **figma-link (optional)** — companion design. Prototype links / frame structure reveal natural flow boundaries.
66
88
 
67
- 3. **Business rule variations.** Same feature, different rules → one story per rule (members / VIP / first-time discounts).
89
+ ### Mixed inputs source-priority
68
90
 
69
- 4. **Data type variations.** One story per data shape (counties / cities / custom areas; or jpg / pdf / mp4). Deliver simplest first.
91
+ - Text canonical for `User Story / Scope / Business Goal` of the epic.
92
+ - Figma / image canonical for `flow structure / candidate children`.
93
+ - Conflicts → BLOCKING `AskUserQuestion`. Never silently expand or shrink scope.
70
94
 
71
- 5. **Data entry / UI complexity.** Basic input first (`YYYY-MM-DD` text); fancy UI (calendar picker, autocomplete, drag-drop) as follow-ups.
95
+ ## Pre-split gate (STOP conditions)
72
96
 
73
- 6. **Major effort.** First implementation does the heavy infrastructure lift; subsequent stories are trivial additions (build Visa payments + infra in story 1; add Mastercard/Amex in story 2).
97
+ Run `[[invest-checklist]]` first:
74
98
 
75
- 7. **Simple / complex.** Strip variations from the core. Story 1 = simplest case that still delivers value; stories 2..N = each variation.
99
+ - **V FAILS** STOP. Not a story. Combine with related user-facing work. Do not split.
100
+ - **T FAILS** → fix in place via `[[story-refine]]`. Splitting untestable input produces untestable children.
101
+ - **N FAILS** → fix in place. Story is over-prescriptive, not too big.
102
+ - **E FAILS due to unknowns** → recommend a spike, not a split.
103
+ - **I / E (size) / S FAIL** → proceed to pattern selection.
76
104
 
77
- 8. **Defer performance.** "Make it work" before "make it fast". Story 1 = functional, no SLA. Story 2 = optimize to <100ms / add caching / scale.
105
+ ## Pattern catalog (apply in order; stop at first that fits)
78
106
 
79
- 9. **Spike (last resort).** None of 1–8 apply because the unknown blocks decomposition. Run a 1–2 day time-boxed investigation answering a specific question ("is this feasible on our stack?", "what does the third-party API actually return?"). A spike is **not a story** — it produces learning, not shippable code. After the spike, restart at pattern 1.
107
+ Humanizing Work methodology (Lawrence & Green).
80
108
 
81
- **Anti-patterns (these are NOT splits):**
82
- - Horizontal slicing (frontend story + backend story) neither child has user value.
83
- - Task decomposition ("set up DB" / "write endpoint" / "build form").
84
- - Meaningless halves ("first half of feature" / "second half").
109
+ 1. **Workflow steps — thin end-to-end slices.** NOT step1/step2 of the journey. Each child delivers the FULL workflow with increasing sophistication.
110
+ - Wrong: editorial / legal / publish. Story 1 alone delivers nothing.
111
+ - Right: publish immediately. Story 2 adds editorial. Story 3 adds legal.
112
+ 2. **CRUD operations.** "Manage" / "handle" / "maintain" → split into C/R/U/D.
113
+ 3. **Business rule variations.** Same feature, different rules (members / VIP / first-time).
114
+ 4. **Data type variations.** One story per data shape (jpg / pdf / mp4).
115
+ 5. **Data entry / UI complexity.** Basic input first; fancy UI (calendar, autocomplete) as follow-ups.
116
+ 6. **Major effort.** First implementation does the heavy infrastructure lift; subsequent stories are trivial additions.
117
+ 7. **Simple / complex.** Strip variations from the core. Story 1 = simplest case that still delivers value.
118
+ 8. **Defer performance.** Make-it-work before make-it-fast.
119
+ 9. **Spike (last resort).** Time-boxed investigation. Not a story.
85
120
 
86
- ### Cynefin domain calibration
121
+ **Anti-patterns (NOT splits):**
122
+ - Horizontal slicing (frontend / backend) — no user value per child.
123
+ - Task decomposition ("set up DB", "write endpoint").
124
+ - Meaningless halves.
87
125
 
88
- Adjust the splitting strategy to uncertainty:
126
+ ## Cynefin domain calibration
89
127
 
90
- - **Obvious / Complicated** — known problem, just engineering. Enumerate all children, prioritize by value/risk.
91
- - **Complex** — unclear what users want or what will work. Don't enumerate exhaustively; produce **1–2 learning stories** that ship something observable, then let real usage teach what to write next.
92
- - **Chaotic** — priorities shifting daily, fires burning. **Defer splitting** until stability returns. Stabilize first.
128
+ - **Obvious / Complicated** — enumerate all children, prioritize by value/risk.
129
+ - **Complex** — produce 1–2 learning stories that ship something observable; let usage teach the rest.
130
+ - **Chaotic** — defer splitting; stabilize first.
93
131
 
94
- ### Meta-pattern (applies across every pattern)
132
+ ## Meta-pattern (every pattern)
95
133
 
96
- For any pattern you pick:
97
134
  1. Name the **core complexity** that makes the story big.
98
135
  2. List **all variations** of that complexity.
99
136
  3. Pick **one variation** as the simplest complete vertical slice.
100
137
  4. Each other variation becomes its own story.
101
138
 
102
- ### Procedure
139
+ ## Application (step-by-step)
140
+
141
+ 0. **Read prior context.** Load `<output-folder>/.storywright-context.json` if present (exact folder only). Apply resolved answers.
142
+
143
+ 1. **Detect input types + companion sources.** Run conflict detection (mixed inputs). Run chrome detection (rule 7).
144
+
145
+ 2. **Language resolution** via rule 4a.
146
+
147
+ 3. **Pre-split gate.** Run `[[invest-checklist]]`. Honor STOP conditions above.
148
+
149
+ 4. **Pattern selection.** Apply catalog in order. Name first fit. Name the meta-pattern's "core complexity". Note Cynefin domain.
150
+
151
+ 5. **Draft split plan** as a terminal table (no file yet):
103
152
 
104
- 1. Run `[[invest-checklist]]` and apply the pre-split gates above. If you should not split, say so explicitly and stop.
105
- 2. Apply the pattern catalog in order. Name the first pattern that fits and the meta-pattern's "core complexity".
106
- 3. **Draft a split plan** as a Markdown table:
107
153
  ```
108
154
  ### Split Plan
155
+ Rationale: <INVEST failure reasons>
156
+ Core complexity: <meta-pattern>
157
+ Pattern(s): <names>
158
+ Cynefin: <domain>
109
159
 
110
- **Rationale (from INVEST failure):**
111
- - S — FAIL: covers web + mobile + account-linking
112
- - E FAIL: account-linking edge cases not scoped
160
+ | # | Proposed child | Pattern | V audit (rule 11) |
161
+ |---|---|---|---|
162
+ | 1 | ... | Workflow simple | PASS / WEAK·merge |
163
+ | 2 | ... | Data variation | PASS |
164
+ ```
113
165
 
114
- **Core complexity (meta-pattern):** authenticating new users + reconciling them with pre-existing accounts.
115
- **Pattern(s) applied:** Workflow steps (thin end-to-end) + Simple→Complex
116
- **Cynefin domain:** Complicated (known problem, just engineering)
166
+ 6. **Strategic check before approval:**
167
+ - Does the split reveal low-value work we can deprioritize or kill?
168
+ - Are the children roughly equal in size?
169
+ If neither holds, try a different pattern.
117
170
 
118
- | # | Proposed child story | Pattern | INVEST hint |
119
- |---|---|---|---|
120
- | 1 | Login Google — simplest path (new account, web) | Workflow / Simple | Smallest complete vertical slice |
121
- | 2 | Login Google mobile | Data variation (surface) | Small, depends on #1 |
122
- | 3 | Account linking — Google ↔ existing email/password | Major effort | Independent flow |
123
- | 4 | Workspace domain restriction | Business rule variation | Independent |
171
+ 7. **STOP and ask the user to approve via `AskUserQuestion`:**
172
+ - Approve → proceed to step 8.
173
+ - Adjust edit, re-loop.
174
+ - Cancel mark original as `NEEDS REFINEMENT`, stop.
175
+
176
+ 8. **For each approved child, write the canonical block** (Use Case + AC + Design Ref + INVEST):
177
+
178
+ ```markdown
179
+ ### [Child Title]
180
+
181
+ #### Use Case
182
+ - **As a** [persona]
183
+ - **I want to** [action]
184
+ - **so that** [outcome — rule G applied]
124
185
 
125
- **Proposed epic title:** Login con Google (multi-surface + linking)
186
+ #### Acceptance Criteria
187
+ - **Scenario:** [single outcome]
188
+ - **Given:** [context — surface nouns drive dep matrix]
189
+ - **When:** [single trigger]
190
+ - **Then:** [single observable outcome]
191
+
192
+ #### Design Reference (optional)
193
+ **Source: <raster | figma | tokens> → <banner from rule 5>**
194
+ - [link / path]
195
+
196
+ #### INVEST
197
+ - I — <PASS | PARTIAL · depends on <Ci>>
198
+ - N/V/E/S/T — one line each
199
+ - **Verdict:** READY | READY (after <Ci> builds) | WEAK·merge-upstream-candidate
200
+
201
+ #### Refinement log (≤3 lines)
202
+ - Split from parent; pattern: <name>.
126
203
  ```
127
- 4. **Split evaluation (strategic check before approval).** Ask:
128
- - **Does the split reveal low-value work we can deprioritize or kill?** Good splits surface 80/20 — e.g., after splitting flight search, "flexible dates" turns out to be rarely used → drop it.
129
- - **Are the children roughly equal in size?** Equal-sized children give PMs prioritization flexibility mid-sprint.
130
- If neither holds, try a different pattern.
131
- 5. **STOP and ask the user to approve the plan.** Options:
132
- - "Approve plan" → proceed to step 6
133
- - "Adjust" → user edits the table or merges/splits rows
134
- - "Cancel" → leave the story unsplit (mark it as `NEEDS REFINEMENT` for the team to negotiate)
135
- 6. **After approval:**
136
- - Write `epic.md` — title, description, child story list, business goal, dependencies between children
137
- - Write one stub per child: title + 1-line user story + open clarifications. **Do not run the full story-generate flow yet** — stubs are placeholders; user invokes `[[story-generate]]` per child when ready.
138
- 7. **Coherence check** — verify the children together cover the original scope. If any child overlaps another or the union has gaps, flag it before saving.
139
- 8. **Recursive re-split check.** For each child, ask: still >1 sprint? If yes, restart at the pattern catalog **for that child**. Keep splitting until every leaf is sprint-shippable. Surface the tree visually in the plan.
140
- 9. **Save all artifacts** under `./stories/<epic-slug>/`:
141
- - `epic.md`
142
- - `story-1.md`, `story-2.md`, …
143
- - `split-plan.md` (the decision trail)
144
204
 
145
- ## Examples
205
+ 9. **Build the dependency matrix mechanically (rule 10).** Parse each child's `Given` lines for surface nouns owned by other children. Emit the matrix in `epic.md`.
146
206
 
147
- ### Good
207
+ 10. **Run V audit per child (rule 11).** Flag merge-upstream candidates in `epic.md`. Recommend merging instead of keeping standalone.
208
+
209
+ 11. **Recursive re-split check.** For each child, run the deterministic counter (rule D). If count ≥2 for any child → recursive split of that child. Surface the tree in `epic.md`.
210
+
211
+ 12. **Coherence check** — verify children together cover the original scope. Flag gaps or overlaps before saving.
212
+
213
+ 13. **Write `epic.md`** at `<output-folder>/`:
214
+
215
+ ```markdown
216
+ ### EPIC: <title>
217
+
218
+ **Why split:** <pattern + core complexity + INVEST failure reasons>
219
+
220
+ **Cynefin domain:** <domain>
221
+
222
+ **Children independence matrix (mechanical, rule 10):**
223
+
224
+ | | C1 | C2 | C3 | ... |
225
+ |--------|----|----|----|-----|
226
+ | C1 | — | | | |
227
+ | C2 |DEP | — | | |
228
+ | ... | | | | |
229
+
230
+ **Build order (topological):** C1 → C2 → ...
148
231
 
149
- Original: "Permitir login con Google" with INVEST failing on Small + Estimable.
232
+ **V audit (rule 11):**
233
+ - C1 — PASS
234
+ - C2 — PASS
235
+ - C3 — WEAK · merge-upstream-candidate (merge into C2)
150
236
 
237
+ **Children:**
238
+ 1. story-1.md — <slug per naming pattern F>
239
+ 2. story-2.md
240
+ ...
241
+
242
+ **Design source:** <raster | figma | tokens>
243
+ ```
244
+
245
+ 14. **Write all `story-N.md` files** and `.storywright-context.json` updated with `split_pattern` and `core_complexity` under `extra`.
246
+
247
+ ## Validate every child (must pass all 6)
248
+
249
+ 1. Delivers user value independently (rule 11 V audit PASS).
250
+ 2. Developable with explicit build order from the matrix (no implicit deps).
251
+ 3. Testable: single Given/When/Then with observable outcome.
252
+ 4. Sprintable (1–5 days work).
253
+ 5. Union equals original scope (coherence check).
254
+ 6. ≤60 lines per child story (anti-PRD via INVEST Small).
255
+
256
+ A "no" on any line → revise the split.
257
+
258
+ ## Examples
259
+
260
+ ### Good
261
+ Original: "Permitir login con Google" with INVEST Small + Estimable FAIL.
151
262
  Split:
152
263
  1. Web — new accounts only (Simple)
153
264
  2. Mobile — new accounts only (Simple)
154
- 3. Account linking with existing email/password (Complex, depends on #1)
155
- 4. Workspace domain restriction (Independent rule)
265
+ 3. Account linking with existing email/password (Major effort)
266
+ 4. Workspace domain restriction (Business rule variation)
156
267
 
157
- Each child is shippable in one sprint, each has clear value, each is testable.
268
+ Matrix mechanical:
269
+ - C2.Given mentions "Google sign-in handshake" owned by C1 → DEP(C2 → C1)
270
+ - C3.Given mentions "Google account exists" owned by C1 → DEP(C3 → C1)
271
+ - C4 independent.
158
272
 
159
- ### Bad
273
+ V audit: all PASS.
160
274
 
161
- Splitting "Permitir login con Google" into "Backend auth endpoint" and "Frontend login button" — that's a **task split**, not a story split. Both halves have no user value alone.
275
+ Build order: C1 {C2, C3} C4 (C4 parallel anytime).
162
276
 
163
- ## Validate every child (must pass all 5)
277
+ ### Good merge recommendation
278
+ Original story produced child "results counter" + child "grid". Counter's V audit:
279
+ - "If only counter ships and no grid exists, does a user complete a task?" → no.
280
+ - V = WEAK · merge-upstream-candidate.
281
+ - Epic recommends merging counter into grid child.
164
282
 
165
- 1. **Delivers user value** independently? (not just "frontend done")
166
- 2. **Developable in isolation** with no hard ordering dependency?
167
- 3. **Testable** with concrete ACs?
168
- 4. **Sprintable** (1–5 days of work, single sprint)?
169
- 5. **Union equals original** — together do they cover the original scope?
283
+ ### Bad
284
+ Splitting "Permitir login con Google" into "Backend auth endpoint" + "Frontend login button". Task split, not story split. Both fail rule 11.
170
285
 
171
- A "no" on any line means revise the split.
286
+ ### Bad
287
+ Claiming all 5 children Independent without running rule 10 matrix.
288
+
289
+ ### Bad
290
+ Writing any sidecar question file. Violates rule 1.
172
291
 
173
292
  ## Common Pitfalls
174
293
 
175
- - **Skipping the pre-split INVEST gate.** Splitting a non-Valuable item produces non-Valuable children. Splitting an untestable item produces untestable children. Fix first, split second.
176
- - **Workflow done step-by-step instead of thin end-to-end.** Story 1 = "review" / Story 2 = "approve" / Story 3 = "publish" means Story 1 alone is invisible to the user. Each child must deliver visible behavior.
177
- - **Horizontal slicing** (frontend / backend / DB). Each child must have user value.
178
- - **Task splits** ("set up DB", "wire API to button"). Tasks aren't stories.
179
- - **Splitting on size alone**, without naming the core complexity or pattern.
180
- - **Forcing a pattern that doesn't fit.** If pattern N doesn't apply, say no and move on; never bend.
181
- - **Auto-splitting without user approval.**
182
- - **Forgetting the coherence check** losing scope in the split.
183
- - **Skipping the strategic evaluation** (low-value reveal, equal sizing).
184
- - **Letting the tree go >5 children** — that's an initiative, not an epic.
185
- - **Splitting in chaos.** Stabilize first; splitting amid shifting priorities just multiplies churn.
294
+ - Skipping the INVEST pre-split gate. Splitting non-V or non-T input.
295
+ - Workflow split done step-by-step instead of thin end-to-end.
296
+ - Horizontal slicing (frontend / backend / DB).
297
+ - Task splits.
298
+ - Splitting on size alone without naming pattern or core complexity.
299
+ - Forcing a pattern that doesn't fit.
300
+ - Auto-splitting without user approval.
301
+ - Skipping the mechanical matrix (rule 10).
302
+ - Skipping per-child V audit (rule 11).
303
+ - Letting tree go >5 children — that's an initiative, not an epic.
304
+ - Splitting in Chaotic Cynefin stabilize first.
305
+ - Re-asking questions already in `.storywright-context.json`.
186
306
 
187
307
  ## References
188
308
 
189
309
  - [[invest-checklist]]
190
310
  - [[story-generate]]
311
+ - [[story-refine]]
191
312
  - [[clarification-questions]]
192
313
 
193
314
  <claude-specific>
194
- - Use extended thinking pattern selection benefits from explicit comparison of options.
195
- - Cache the 8-pattern catalog.
315
+ - Use extended thinking for pattern selection (compare options explicitly).
316
+ - Cache the 9-pattern catalog and the v2.2 hard-rule list.
317
+ - Build the dependency matrix from Given-text parsing (rule 10), not intuition.
318
+ - Run V audit per child (rule 11) and flag merge candidates loudly.
319
+ - Never call Write for any sidecar question file. Use `AskUserQuestion`.
320
+ - Read `.storywright-context.json` ONLY from the exact target output folder.
196
321
  </claude-specific>