@pavp/storywright 1.5.0 → 1.6.1

package/skills/story-split/SKILL.md

@@ -1,196 +1,186 @@
 ---
 name: story-split
-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.
+description: Split an oversize story into an epic plus Cohn+Gherkin children. Mechanical NxN dep matrix and per-child V audit. Inherits all hard rules from storywright-base.
 trigger: "/story-split | split this story | divide this story | dividir historia | this is too big"
-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.
-version: 1.0.0
+intent: Splitting skill driven by INVEST failure reasons. Behavior 100% identical to siblings except for source (oversize story) and split-behavior (ALWAYS produces epic + N children, never a single story).
+version: 2.3.0
 inputs:
   - text
   - image
   - figma-link
 outputs:
-  - split-plan.md
   - epic.md
-  - story-1.md, story-2.md, ... (N child stubs)
+  - story-1.md
+  - story-2.md
+  - .storywright-context.json
 composes:
+  - _components/storywright-base
   - _components/invest-checklist
   - _components/clarification-questions
+  - _components/acceptance-criteria
+  - _components/jira-wiki-formatter
 ---
 
 ## Purpose
 
-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.
+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.
 
-## When to use
+**All hard rules, canonical output shape, language detection, terminal-only Q, mechanical NxN dep matrix, per-child V audit, context persistence, and INVEST handling live in `[[storywright-base]]`. Read that first. Anything in this file is a SOURCE-SPECIFIC or SPLIT-BEHAVIOR delta only.**
 
-- `[[invest-checklist]]` returned `SPLIT RECOMMENDED` (failures on I, E, or S).
-- User explicitly asks: "this story is too big, split it".
-- Input visibly mixes ≥2 flows.
+## Source-specific differential
 
-## Inputs & interpretation
+- **Source:** an oversize story (any prior source — generate / refine / from-figma may all hand off here). The story has failed INVEST on I, E, or S — OR the deterministic pre-split count is ≥2.
+- **What changes vs base:** the skill does NOT produce a single story. It ALWAYS produces an epic + N children. Each child obeys the base canonical block. The user must approve the split plan before children are written.
 
-- **text** — the oversize story (or a one-line goal that's clearly epic-scoped).
-- **image (optional)** — companion mockup. Use to validate scope and reveal hidden sub-flows the text doesn't mention.
-- **figma-link (optional)** — companion design. Often makes splitting easier: prototype links and frame structure reveal natural flow boundaries that map to children.
+## Split behavior differential
 
-### Mixed inputs
+This skill IS the split behavior. It always emits multiple files:
+- `epic.md` — title, why-split, INVEST failure reasons, mechanical NxN matrix, build order, V audit per child, list of children.
+- `story-1.md`, `story-2.md`, … — one canonical story per child (per base shape).
+- `.storywright-context.json` — persisted answers.
 
-When the user provides text + image / Figma alongside the story:
-- **Text is canonical for User Story / Scope / Business Goal** of the epic.
-- **Figma / image is canonical for flow structure** — use prototype links to enumerate candidate sub-flows. Each flow is a candidate child story.
-- **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.
-- See `[[story-generate]]` "Mixed inputs" for the full source-priority matrix.
+NO `split-plan.md`. The plan lives inside `epic.md`.
 
-## Application (step-by-step)
+### Pre-split gate (STOP conditions) — run BEFORE pattern selection
 
-### Pre-split gate — STOP conditions
+Run `[[invest-checklist]]` first:
+- **V FAILS** → STOP. Not a story. Combine with related user-facing work.
+- **T FAILS** → fix in place via `[[story-refine]]`.
+- **N FAILS** → fix in place. Story is over-prescriptive, not too big.
+- **E FAILS due to unknowns** → recommend a spike, not a split.
+- **I / E (size) / S FAIL** → proceed to pattern selection.
 
-Before splitting anything, run `[[invest-checklist]]` and apply these gates:
+### Pattern catalog (apply in order; stop at first that fits)
 
-- **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.
-- **Testable FAILS** → **fix in place** via `[[story-refine]]` first. Splitting an untestable story produces untestable children.
-- **Negotiable FAILS** → fix in place; the story is over-prescriptive, not too big.
-- **Estimable FAILS due to unknowns** → run a **spike** (Pattern 9 below), not a split.
-- **Independent / Estimable / Small FAIL** → continue to pattern selection.
+Humanizing Work methodology (Lawrence & Green).
 
-### Pattern catalog (apply in order; stop at first that fits)
+1. **Workflow steps — thin end-to-end slices.** Each child delivers the FULL workflow with increasing sophistication. NOT step1/step2 of the journey.
+   - ❌ Wrong: editorial / legal / publish.
+   - ✅ Right: publish immediately. Story 2 adds editorial. Story 3 adds legal.
+2. **CRUD operations.** "Manage" / "handle" / "maintain" → C/R/U/D.
+3. **Business rule variations.** Same feature, different rules (members / VIP / first-time).
+4. **Data type variations.** One story per data shape (jpg / pdf / mp4).
+5. **Data entry / UI complexity.** Basic input first; fancy UI as follow-ups.
+6. **Major effort.** First implementation does the heavy infrastructure lift.
+7. **Simple / complex.** Strip variations from the core. Story 1 = simplest case that still delivers value.
+8. **Defer performance.** Make-it-work before make-it-fast.
+9. **Spike (last resort).** Time-boxed investigation. Not a story.
 
-Based on the Humanizing Work splitting methodology (Richard Lawrence & Peter Green).
+**Anti-patterns (NOT splits):** horizontal slicing (FE/BE), task decomposition, meaningless halves.
 
-1. **Workflow steps — thin end-to-end slices.**
-   **Critical:** this is NOT "step 1 / step 2 / step 3" of the journey. Each child must deliver the **full** workflow with increasing sophistication.
-   - ❌ Wrong: Story 1 = editorial review, Story 2 = legal approval, Story 3 = publish. (Story 1 alone delivers nothing observable to the user.)
-   - ✅ Right: Story 1 = publish post immediately, no reviews. Story 2 = add editorial review step. Story 3 = add legal step. Each story produces visible behavior.
+### Cynefin domain calibration
 
-2. **CRUD operations.** When the input says "manage" / "handle" / "maintain", it bundles operations. Split into Create / Read / Update / Delete.
+- **Obvious / Complicated** — enumerate all children, prioritize by value/risk.
+- **Complex** — produce 1–2 learning stories; let usage teach the rest.
+- **Chaotic** — defer splitting; stabilize first.
 
-3. **Business rule variations.** Same feature, different rules → one story per rule (members / VIP / first-time discounts).
+### Meta-pattern (every pattern)
 
-4. **Data type variations.** One story per data shape (counties / cities / custom areas; or jpg / pdf / mp4). Deliver simplest first.
+1. Name the **core complexity** that makes the story big.
+2. List **all variations** of that complexity.
+3. Pick **one variation** as the simplest complete vertical slice.
+4. Each other variation becomes its own story.
 
-5. **Data entry / UI complexity.** Basic input first (`YYYY-MM-DD` text); fancy UI (calendar picker, autocomplete, drag-drop) as follow-ups.
+## Application (step-by-step)
 
-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).
+Follow the **base Application** skeleton for the front-end behaviors (context load, language, persona, passive-goal, gap-check, siblings). Split-specific steps inserted after:
 
-7. **Simple / complex.** Strip variations from the core. Story 1 = simplest case that still delivers value; stories 2..N = each variation.
+1. **Pre-split gate.** Run `[[invest-checklist]]`. Honor STOP conditions above.
 
-8. **Defer performance.** "Make it work" before "make it fast". Story 1 = functional, no SLA. Story 2 = optimize to <100ms / add caching / scale.
+2. **Pattern selection.** Apply catalog in order. Name first fit + core complexity + Cynefin domain.
 
-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.
+3. **Draft split plan** as a terminal table (no file yet):
+   ```
+   ### Split Plan
+   Rationale: <INVEST failure reasons>
+   Core complexity: <meta-pattern>
+   Pattern(s): <names>
+   Cynefin: <domain>
 
-**Anti-patterns (these are NOT splits):**
-- Horizontal slicing (frontend story + backend story) — neither child has user value.
-- Task decomposition ("set up DB" / "write endpoint" / "build form").
-- Meaningless halves ("first half of feature" / "second half").
+   | # | Proposed child | Pattern | V audit (base rule 11) |
+   |---|---|---|---|
+   ```
 
-### Cynefin domain calibration
+4. **Strategic check before approval:**
+   - Does the split reveal low-value work we can deprioritize?
+   - Are children roughly equal in size?
 
-Adjust the splitting strategy to uncertainty:
+5. **STOP and ask the user to approve via `AskUserQuestion`.**
 
-- **Obvious / Complicated** — known problem, just engineering. Enumerate all children, prioritize by value/risk.
-- **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.
-- **Chaotic** — priorities shifting daily, fires burning. **Defer splitting** until stability returns. Stabilize first.
+6. **For each approved child, write the base canonical block.** Each child is its own file (`story-<N>.md`).
 
-### Meta-pattern (applies across every pattern)
+7. **Build dependency matrix mechanically (base rule 10).** Render in `epic.md`.
 
-For any pattern you pick:
-1. Name the **core complexity** that makes the story big.
-2. List **all variations** of that complexity.
-3. Pick **one variation** as the simplest complete vertical slice.
-4. Each other variation becomes its own story.
+8. **V audit per child (base rule 11).** Flag merge-upstream candidates in `epic.md`.
 
-### Procedure
+9. **Recursive re-split check.** For each child, run the base deterministic counter. If count ≥2 → recursive split of that child. Surface the tree in `epic.md`.
 
-1. Run `[[invest-checklist]]` and apply the pre-split gates above. If you should not split, say so explicitly and stop.
-2. Apply the pattern catalog in order. Name the first pattern that fits and the meta-pattern's "core complexity".
-3. **Draft a split plan** as a Markdown table:
-   ```
-   ### Split Plan
+10. **Coherence check** — children together cover the original scope. Flag gaps or overlaps.
 
-   **Rationale (from INVEST failure):**
-   - S — FAIL: covers web + mobile + account-linking
-   - E — FAIL: account-linking edge cases not scoped
+11. **Write `epic.md`** with: why-split, Cynefin, matrix, build order, V audit, list of children.
 
-   **Core complexity (meta-pattern):** authenticating new users + reconciling them with pre-existing accounts.
-   **Pattern(s) applied:** Workflow steps (thin end-to-end) + Simple→Complex
-   **Cynefin domain:** Complicated (known problem, just engineering)
+12. **Persist context** to `.storywright-context.json` (`extra.split_pattern`, `extra.core_complexity`).
 
-   | # | Proposed child story | Pattern | INVEST hint |
-   |---|---|---|---|
-   | 1 | Login Google — simplest path (new account, web) | Workflow / Simple | Smallest complete vertical slice |
-   | 2 | Login Google — mobile | Data variation (surface) | Small, depends on #1 |
-   | 3 | Account linking — Google ↔ existing email/password | Major effort | Independent flow |
-   | 4 | Workspace domain restriction | Business rule variation | Independent |
+## Validate every child (must pass all 6)
 
-   **Proposed epic title:** Login con Google (multi-surface + linking)
-   ```
-4. **Split evaluation (strategic check before approval).** Ask:
-   - **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.
-   - **Are the children roughly equal in size?** Equal-sized children give PMs prioritization flexibility mid-sprint.
-   If neither holds, try a different pattern.
-5. **STOP and ask the user to approve the plan.** Options:
-   - "Approve plan" → proceed to step 6
-   - "Adjust" → user edits the table or merges/splits rows
-   - "Cancel" → leave the story unsplit (mark it as `NEEDS REFINEMENT` for the team to negotiate)
-6. **After approval:**
-   - Write `epic.md` — title, description, child story list, business goal, dependencies between children
-   - 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.
-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.
-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.
-9. **Save all artifacts** under `./stories/<epic-slug>/`:
-   - `epic.md`
-   - `story-1.md`, `story-2.md`, …
-   - `split-plan.md` (the decision trail)
+1. Delivers user value independently (V audit PASS).
+2. Developable with explicit build order from the matrix.
+3. Testable: single Given/When/Then with observable outcome.
+4. Sprintable (1–5 days).
+5. Union equals original scope.
+6. ≤60 lines per child story (anti-PRD via base rule 8).
 
 ## Examples
 
 ### Good
-
-Original: "Permitir login con Google" with INVEST failing on Small + Estimable.
-
-Split:
+Original: "Permitir login con Google" — INVEST Small + Estimable FAIL.
+Children:
 1. Web — new accounts only (Simple)
 2. Mobile — new accounts only (Simple)
-3. Account linking with existing email/password (Complex, depends on #1)
-4. Workspace domain restriction (Independent rule)
+3. Account linking with existing email/password (Major effort)
+4. Workspace domain restriction (Business rule variation)
 
-Each child is shippable in one sprint, each has clear value, each is testable.
+Matrix mechanical:
+- C2.Given mentions "Google sign-in handshake" owned by C1 → DEP(C2 → C1)
+- C3.Given mentions "Google account exists" owned by C1 → DEP(C3 → C1)
+- C4 independent.
 
-### Bad
+V audit: all PASS. Build order: C1 → {C2, C3} → C4.
 
-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.
+### Good — merge recommendation
+"Results counter" child V audit:
+- "If only counter ships, no grid, does a user complete a task?" → no.
+- V = WEAK · merge-upstream-candidate. Recommend merging into the grid child.
 
-## Validate every child (must pass all 5)
-
-1. **Delivers user value** independently? (not just "frontend done")
-2. **Developable in isolation** with no hard ordering dependency?
-3. **Testable** with concrete ACs?
-4. **Sprintable** (1–5 days of work, single sprint)?
-5. **Union equals original** — together do they cover the original scope?
+### Bad
+Splitting into "Backend auth endpoint" + "Frontend login button". Task split, no user value per child. Fails base rule 11.
 
-A "no" on any line means revise the split.
+### Bad
+Claiming children Independent without running the mechanical matrix (base rule 10).
 
-## Common Pitfalls
+## Common Pitfalls (split-specific)
 
-- **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.
-- **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.
-- **Horizontal slicing** (frontend / backend / DB). Each child must have user value.
-- **Task splits** ("set up DB", "wire API to button"). Tasks aren't stories.
-- **Splitting on size alone**, without naming the core complexity or pattern.
-- **Forcing a pattern that doesn't fit.** If pattern N doesn't apply, say no and move on; never bend.
-- **Auto-splitting without user approval.**
-- **Forgetting the coherence check** — losing scope in the split.
-- **Skipping the strategic evaluation** (low-value reveal, equal sizing).
-- **Letting the tree go >5 children** — that's an initiative, not an epic.
-- **Splitting in chaos.** Stabilize first; splitting amid shifting priorities just multiplies churn.
+- Skipping the pre-split INVEST gate.
+- Workflow split done step-by-step instead of thin end-to-end.
+- Horizontal slicing (FE/BE/DB).
+- Task splits.
+- Splitting on size alone without naming a pattern or core complexity.
+- Auto-splitting without user approval.
+- Letting the tree go >5 children — that's an initiative, not an epic.
+- Splitting in Chaotic Cynefin — stabilize first.
+- All other pitfalls in `[[storywright-base]]` apply equally.
 
 ## References
 
+- [[storywright-base]] — the rulebook
 - [[invest-checklist]]
 - [[story-generate]]
-- [[clarification-questions]]
+- [[story-refine]]
+- [[story-from-figma]]
 
 <claude-specific>
-- Use extended thinking — pattern selection benefits from explicit comparison of options.
-- Cache the 8-pattern catalog.
+- Read `[[storywright-base]]` before applying. Do not duplicate its rules in your reasoning.
+- Use extended thinking for pattern selection (compare options explicitly).
+- Cache the 9-pattern catalog.
+- Build the dependency matrix from Given-text parsing (base rule 10), not intuition.
 </claude-specific>