@pavp/storywright 1.6.0 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/storywright",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "PM Skills pack for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
   "keywords": [
     "claude",

package/skills/_components/jira-wiki-formatter/SKILL.md

@@ -119,6 +119,8 @@ Permitir a usuarios autenticarse mediante OAuth con Google.
 - Forgetting that Jira's `{code}` block doesn't support all languages — fall back to `{noformat}` for plain text.
 - Emoji in Jira: works in cloud, often mangled in older self-hosted. Keep emojis to non-critical decoration.
 - Empty headings. Drop.
+- Wrong heading levels: CommonMark output uses `#` (H1) for title, `##` (H2) for sections. Jira uses `h2.` for title, `h3.` for sections. The canonical block in `[[storywright-base]]` uses `###`/`####` as taxonomy shorthand only — do not copy those levels into the rendered artifact.
+- Emitting INVEST as a section: INVEST is a process step. Its verdict belongs in the log line only (`INVEST Verdict: READY`), never as a standalone section in the output file.
 
 ## References
 

package/skills/_components/storywright-base/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: storywright-base
+description: Shared base behavior for all storywright top-level skills. Hard rules, canonical output, terminal-only Q, context schema, mechanical deps, V audit, language detect.
+trigger: "internal use by story-* skills"
+intent: Component skill that holds the v2.2 baseline. Top-level skills (story-generate, story-refine, story-split, story-from-figma) compose this and add only their source-specific behavior on top.
+version: 2.2.0
+inputs:
+  - none
+outputs:
+  - none
+---
+
+## Purpose
+
+Every top-level storywright skill must behave identically except for three things:
+
+1. **Source** — what the input is (raw prompt / existing story / oversize story / Figma URL).
+2. **Prompt** — what the user is asking for.
+3. **Split behavior** — whether the skill produces 1 story, recommends a split, or produces N stories directly.
+
+Everything else (how to ask questions, what shape the output takes, how to detect language, how to count outcomes, how to flag dependencies, how to persist context) lives here.
+
+If you are reading this through a top-level skill, treat every rule below as non-negotiable for that skill too.
+
+## Hard rules (v2.2 — apply to all top-level storywright skills)
+
+1. **Terminal-only clarifications.** Never write any sidecar question file (no `clarifications.md`, no `questions.md`, nothing). All gap questions go through `AskUserQuestion`, batched ≤4 per call. Non-blocking gaps → mark `⚠️ Assumed: <text>` inline in the story body — do not ask.
+
+2. **Cohn + Gherkin canonical.** Every story (or child story) has:
+   - ONE Use Case block (`As a / I want to / so that`).
+   - ONE AC Scenario (one Given chain + one `When` + one `Then`).
+   If the input naturally needs >1 `When`/`Then`, the skill MUST stop the single-story path and route to `[[story-split]]`.
+
+3. **No mini-PRDs.** PROHIBITED sections in any story output:
+   - Non-Functional Requirements blocks (a11y/i18n/perf/tokens) — DoD only.
+   - Edge Cases enumerated as their own section — fold into AC failure paths.
+   - Dependencies as prose — Jira ticket links only.
+   - Per-claim visual specs (pixel measurements, hex inferences) inline — use single banner (rule 5).
+   - Logs >3 lines (>5 if SPLIT verdict).
+
+4. **Output language matches the user's chat language**, not the input's. Auto-detect first via rule 4a; only ask via `AskUserQuestion` if signals split.
+
+5. **Visual inference confidence — single banner only.** Do NOT tag every visual claim. ONE banner at the top of the Design Reference block declares source type; all claims under it inherit:
+   - Raster source (PNG/JPG) → `**Source: raster mockup → all visual specs are pixel-derived, not token-confirmed.**`
+   - Figma source → `**Source: Figma → values can be tokenized at implementation.**`
+   - Design-token source → `**Source: design tokens → values are authoritative.**`
+   Never assert hex / px / spacing from raster without the raster banner.
+
+6. **Sibling task IDs.** If the story references "next task / future task / another story / siblings" — check `<output-folder>/.storywright-context.json` first. If unresolved, ask via `AskUserQuestion`. If user has none yet, leave `TODO: link sibling` (unless rule F applies — invent slug per persisted naming pattern).
+
+7. **Mockup chrome detection — closed list.** Chrome = exactly:
+   - left nav rail / sidebar
+   - top bar (user menu, global breadcrumbs, global search)
+   - footer
+   - persistent toast/snackbar slot
+   - persistent modal scrim
+   - app-level tabs
+
+   If a companion image shows any of these AND the input does not mention them, ask via `AskUserQuestion` whether each is `in-scope`, `sibling-scope`, or `out-of-scope`. Anything not on this list (cards, section headers, in-flow buttons) is NOT chrome — do not surface as a chrome question.
+
+8. **Anti-PRD is part of INVEST `Small`, not a separate step.** See `[[invest-checklist]]` Small criterion — line-count ceiling (~60 lines) lives there. Single source of truth.
+
+9. **Cross-skill context persistence.** When any storywright skill resolves a clarification via `AskUserQuestion`, write the **answer** to `<output-folder>/.storywright-context.json`. Read only from the exact output folder of the current invocation; never search siblings or parents. Schema:
+
+   ```json
+   {
+     "version": 1,
+     "decided_at": "<ISO date>",
+     "decided_by_skill": "story-generate | story-refine | story-split | story-from-figma",
+     "language": "EN | ES | ...",
+     "chrome_scope": "in-scope | in-scope-placeholder | sibling | out-of-scope",
+     "siblings": "TODO | <list of IDs> | not-applicable",
+     "design_source": "raster | figma | tokens",
+     "naming_pattern": "kebab-feature-action | verb-noun | domain-action | jira-prefix",
+     "extra": {}
+   }
+   ```
+
+   Every skill MUST read this file BEFORE asking any question. Every skill MUST write this file when it resolves a question.
+
+10. **Children independence — mechanical detection (rule A).** When any skill produces multiple stories or children (story-split, story-from-figma multi-flow, story-refine recommending split):
+    - For each child Cj, parse its `Given:` and `and Given:` lines.
+    - If any Given text contains a surface noun owned by child Ci (Ci's title/scope owns "grid" and Cj's Given mentions "the grid") → mark `DEP(Cj → Ci)`.
+    - The dependency map IS the union of those text matches. **Do not add deps "you sense" without a Given citation.**
+    - Affected child's INVEST `Independent` becomes `PARTIAL · depends on <Ci>`.
+    - Parent epic / flow-summary file lists explicit build order (topological sort of the matrix).
+    - If a dep is real but no Given mentions it, rewrite the child's Given to make it explicit, then re-run the match. Intuition-based deps are forbidden.
+
+11. **Per-child V audit (rule C).** After any split-style output, for each candidate child run a one-line test:
+    "If only this child ships and no sibling exists, does a real user complete a real task?"
+    - If yes → V = PASS.
+    - If no, useless until `<other>` ships → V = `WEAK · merge-upstream-candidate`. Recommend merging into the parent surface instead of keeping standalone.
+    Do not let stylistic/UI-fragment children survive a split.
+
+12. **Passive-goal downstream prompt (rule G).** If the story's `I want to` verb is observational (`view, see, read, browse, look at, inspect, monitor`) AND the `so that` does not name a follow-up user action — ask once via `AskUserQuestion`: "What does the user do with this?". Strengthen the `so that` accordingly. Skip if `so that` already names a downstream action.
+
+### 4a. Language auto-detect — expanded signals (rule E)
+
+Run cheap detection before asking. Multi-signal weighted decision:
+
+| Signal | Where to look | Weight |
+|---|---|---|
+| Gherkin keywords in M ("Given/When/Then") | AC block | high |
+| Persona phrasing in M ("As a user" vs "Como un usuario") | Use Case | high |
+| Column / field names in M ("Phone - primary", "Teléfono - principal") | AC bullets | medium |
+| Domain verbs in M ("clicking" vs "hacer clic") | AC bullets | medium |
+| Figma frame names / layer text in M (when source = figma) | design source | medium |
+| Title language | header | low |
+
+**Decision:**
+- All high+medium signals agree on language M → adopt M silently. Mark inline `⚠️ Assumed: output language = <M> (auto-detected from <signals>)`.
+- Signals split → ask once via `AskUserQuestion`.
+- User chat = L, story body = M, but high signals tie → prefer M (story body is contract).
+
+Persist via rule 9.
+
+### Rule D. Surface vs styling (deterministic)
+
+A "named UI surface" counts as a separate outcome (+1 in the pre-split counter) ONLY if it has its own user goal — a verb in the input where the user *does something with that surface* (clicks it, navigates with it, reads it, configures it).
+
+If a noun is mentioned only in a styling context (color, padding, alignment, background) or as a sub-component of a parent surface (column inside a grid, label inside a button) → it is NOT a surface. It is styling. Count = 0.
+
+Examples:
+- "header row visually distinct (purple)" → styling of grid → 0
+- "pagination control with page numbers" → surface with user goal (navigating) → +1
+- "5 columns: Code, Name, Phone, ..." → sub-components of grid → 0 (grid still counts once)
+- "results counter next to search button" → surface with user goal (reading count) → +1
+
+### Rule F. Naming pattern — ask once, persist
+
+When any skill needs to invent a tentative ticket slug AND `.storywright-context.json` has no `naming_pattern` field, ask once via `AskUserQuestion`:
+
+```
+Which naming pattern do you use for tickets?
+- kebab-case feature-action      → "customer-search-bar-wire"
+- verb-noun                       → "wire-search-bar"
+- domain-action                   → "search.customer.wire-input"
+- Jira prefix + numeric           → "CSB-001"
+```
+
+Persist in `naming_pattern`. Use for all sibling slugs in this run AND future skills reading the same context file.
+
+### Deterministic pre-split test (used by all skills)
+
+Mechanical counter. Apply the table — do NOT eyeball:
+
+| Signal | Hit value |
+|---|---|
+| AC bullet starting with action verb at user level ("clicking", "submitting", "entering", "navigating") | +1 each |
+| Distinct `When [event]` phrasing already implied in the story | +1 each |
+| Distinct named UI surface mentioned at the AC level (rule D applies) | +1 each |
+
+**Do NOT count:**
+- sub-bullets describing the same flow
+- styling of an existing surface
+- preconditions or passive "rendered" statements
+
+**Decision:**
+- Count ≤1 → proceed with single-story path.
+- Count ≥2 → STOP single-story path. Route to split behavior per the host skill (recommend `/story-split`, produce epic+children, or recurse).
+
+## Canonical output shape (this is the WHOLE story — no exceptions)
+
+> **Note:** This block shows the *section taxonomy and rules* — not heading levels or exact markup. The rendered artifact must follow the `story-generate/templates/` files exactly: `#` for title, `##` for sections (CommonMark) or `h2.`/`h3.` (Jira wiki). INVEST is a **process step** — it informs the Verdict line in the log but is NOT emitted as a section in the output artifact.
+
+```markdown
+### [Title]
+
+#### Use Case
+- **As a** [persona — never just "user"]
+- **I want to** [action]
+- **so that** [outcome with downstream action — rule G]
+
+#### Preconditions (optional, only if user provided)
+- ...
+
+#### Out of Scope (optional, only if user provided)
+- ...
+
+#### Acceptance Criteria
+- **Scenario:** [single-outcome scenario name]
+- **Given:** [context — surface nouns here drive dep matrix per rule 10]
+- **and Given:** [context]
+- **When:** [single trigger]
+- **Then:** [single observable outcome]
+
+#### Design Reference (optional)
+**Source: <raster | figma | tokens> → <banner from rule 5>**
+- [link or path]
+- visual notes: [...]
+
+#### <Generation | Refinement | Split> log (≤3 lines; ≤5 if SPLIT verdict)
+- INVEST Verdict: <READY | SPLIT RECOMMENDED | NEEDS REFINEMENT | NOT A STORY>
+- [other changes]
+```
+
+NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No Assumptions block (assumptions get `⚠️ Assumed` inline or are resolved via `AskUserQuestion`). No standalone INVEST section — verdict belongs in the log only.
+
+## Application (step-by-step — every skill follows this skeleton)
+
+0. **Detect companion sources** (image, figma-link, accompanying text). Run conflict detection against the primary input. Run chrome detection using rule 7. Surface conflicts as BLOCKING `AskUserQuestion`.
+
+1. **Read prior context.** Load `<output-folder>/.storywright-context.json` if present (exact folder only). Apply resolved answers; skip the corresponding questions.
+
+2. **Language resolution** via rule 4 + 4a. Auto-detect using the expanded signal table; ask only if signals split. Persist via rule 9.
+
+3. **Persona sharpening.** If persona is "user" / "customer" / "person", ask via `AskUserQuestion` for a specific role. Generic personas hide motivation.
+
+4. **Passive-goal check (rule G).** If `I want to` is observational AND `so that` lacks downstream action → ask once.
+
+5. **Gap-check.** For each weak/missing section:
+   - **Blocking** (changes scope, AC outcome, or persona) → `AskUserQuestion` immediately (batched ≤4).
+   - **Non-blocking** (additive detail) → fill inline marked `⚠️ Assumed: <text>`. Do not ask.
+
+6. **Sibling reference check.** If unlinked references found → ask once. If user opts for tentative slugs, apply rule F. Persist via rule 9.
+
+7. **Deterministic pre-split test.** Apply the table above mechanically.
+   - Count ≤1 → continue to step 8 (single-story path).
+   - Count ≥2 → execute the **host skill's split behavior** (see Source-specific differential in each top-level skill).
+
+8. **Fill the canonical block** (Use Case + AC + Design Ref + INVEST). Preserve original wording where it was already good. NEVER invent NFR/edge-case/deps sections.
+
+9. **Run INVEST** via `[[invest-checklist]]`.
+   - `READY` → render.
+   - `SPLIT RECOMMENDED` → host-skill split behavior + rule 10 matrix + rule 11 V audit.
+   - `NEEDS REFINEMENT` → iterate failing dimension, max 1 cycle, then STOP.
+   - `NOT A STORY` → tell user it's a tech task and stop.
+
+10. **Render** via `[[jira-wiki-formatter]]`. Files: `story.standard.md` + `story.jira-wiki.md`. Plus `.storywright-context.json`. No other files.
+
+11. **Log** ≤3 bullets (≤5 if SPLIT) appended at story end. Log type label is host-specific (Generation / Refinement / Split).
+
+## What each top-level skill adds on top of this base
+
+Only these three things vary:
+
+| Skill | Source | Split behavior |
+|---|---|---|
+| `story-generate` | Raw prompt / ambiguous text + optional image/Figma | If pre-split count ≥2 → STOP, recommend `/story-split`. Otherwise draft 1 story. |
+| `story-refine` | Existing story text + optional image/Figma | If pre-split count ≥2 → STOP, recommend `/story-split`. Otherwise fix in place. |
+| `story-split` | Oversize story (any source) | Always produces epic + N children. Mechanical NxN matrix + per-child V audit MANDATORY. Recursive re-split per child if count ≥2. |
+| `story-from-figma` | Figma file/page/frame URL (+ optional companion text) | One story per logical user-goal flow. Multi-flow output → mandatory `flow-summary.md` with mechanical matrix + V audit. Any flow with count ≥2 → hand off to `[[story-split]]`. |
+
+Everything else is identical and lives in this base.
+
+## Common Pitfalls (all skills)
+
+- Writing any sidecar question file (clarifications.md, questions.md, etc).
+- Skipping rule 1 (terminal-only) "because the user is async".
+- Eyeballing outcome counts instead of running the mechanical table.
+- Renumbering ACs the team may already reference externally.
+- Adding NFR/edge-cases sections "to be thorough".
+- Tagging every visual claim instead of using the single Design Reference banner.
+- Claiming children Independent without running the rule 10 matrix.
+- Letting stylistic/UI-fragment children survive (rule 11 should have flagged them).
+- Asking for a downstream action and then not strengthening the `so that`.
+- Re-asking questions already answered in `.storywright-context.json`.
+- Reading `.storywright-context.json` from a sibling or parent folder.
+
+## References
+
+- [[invest-checklist]]
+- [[acceptance-criteria]]
+- [[clarification-questions]]
+- [[jira-wiki-formatter]]
+- [[story-generate]]
+- [[story-refine]]
+- [[story-split]]
+- [[story-from-figma]]
+
+<claude-specific>
+- Treat every rule above as load-bearing across all top-level skills.
+- Use extended thinking when applying rule 10 (parse Given lines) and rule 11 (V audit per child).
+- Never call Write for any sidecar question file. Use `AskUserQuestion`.
+- Read `.storywright-context.json` ONLY from the exact target output folder.
+- When you find yourself about to add an NFR / edge-cases / dependencies prose section to a story body, STOP — rule 3 forbids it.
+</claude-specific>

package/skills/story-from-figma/SKILL.md

@@ -1,17 +1,18 @@
 ---
 name: story-from-figma
-description: Generate Cohn+Gherkin user stories from a Figma URL. Maps prototype flows to stories (one per user goal, not per frame). Asks ONLY in terminal.
+description: Generate Cohn+Gherkin user stories from a Figma URL. One story per user-goal flow, not per frame. Inherits all hard rules from storywright-base.
 trigger: "/story-from-figma | story from figma | generate from figma | analizar figma | https://www.figma.com/"
-intent: Multimodal entrypoint. Inspects a Figma design, infers flows and screens, and emits one canonical story per logical user goal. Honors v2.2 hard rules (terminal-only Q, no mini-PRD, mechanical deps for split, V audit per child).
-version: 2.2.0
+intent: Multimodal entrypoint. Behavior 100% identical to siblings except for source (Figma URL via MCP, with PNG fallback) and split-behavior (one canonical story per logical user-goal flow; flows with count ≥2 routed to /story-split).
+version: 2.3.0
 inputs:
   - figma-link
 outputs:
-  - story-<N>.standard.md
-  - story-<N>.jira-wiki.md
+  - story-1.standard.md
+  - story-1.jira-wiki.md
   - flow-summary.md
   - .storywright-context.json
 composes:
+  - _components/storywright-base
   - _components/clarification-questions
   - _components/acceptance-criteria
   - _components/invest-checklist
@@ -20,172 +21,77 @@ composes:
 
 ## Purpose
 
-A Figma file usually represents N screens / N flows. This skill maps that visual structure into Cohn+Gherkin stories — **one story per logical user goal, not one per frame**. Splits aggressively if any flow has multiple outcomes.
+A Figma file usually represents N screens / N flows. This skill maps that visual structure into Cohn+Gherkin stories — **one story per logical user goal, not one per frame**.
 
-## Hard rules (v2.2 parity with refine/generate/split)
+**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.**
 
-1. **Terminal-only clarifications.** Never write any sidecar question file (no `clarifications.md`). All gap questions through `AskUserQuestion`, batched ≤4. Non-blocking gaps → `⚠️ Assumed` inline.
+## Source-specific differential
 
-2. **Cohn + Gherkin canonical per story.** Each generated story has ONE Use Case + ONE AC scenario (one Given chain + one `When` + one `Then`). If a flow naturally has >1 `When`/`Then` → STOP and hand off to `[[story-split]]`.
+- **Source:** a Figma file/page/frame URL, accessed via MCP Figma server. Falls back to PNG screenshots if MCP is unavailable.
+- **What changes vs base:**
+  - **Design Reference banner is always Figma** (`**Source: Figma → values can be tokenized at implementation.**`) when MCP is used. Switches to the raster banner if user falls back to PNGs.
+  - **Persona / Goal inferred from prototype flow + frame text** (rule 4a base signal table includes Figma frame names and layer text as medium-weight signals).
+  - **One story per logical user-goal flow**, not per frame. Group frames by prototype-link connectivity to identify flows.
+  - **Companion text overrides Figma** for `User Story / Scope / Business Goal` if both are present. Figma is canonical for `Components / States / Flow structure`.
 
-3. **No mini-PRDs.** Prohibited in each generated story:
-   - NFR blocks — DoD only
-   - Edge Cases enumerations as a section — fold into AC failure paths
-   - Dependencies as prose — Jira links only
-   - Per-claim visual specs — single banner (rule 5)
-   - Generation logs >3 lines (>5 if SPLIT recommended)
+## Split behavior differential
 
-4. **Output language matches the user's chat language**, not the Figma file's. Auto-detect via rule 4a; ask only if signals split. Persist via rule 9.
+This skill may produce **multiple stories in one invocation** (one per flow). When N>1:
+- **MANDATORY: emit `flow-summary.md`** with:
+  - Per-story INVEST verdict
+  - Mechanical NxN dep matrix (base rule 10) parsed from each story's Given lines
+  - Per-story V audit (base rule 11) with merge-upstream flags
+  - Topological build order
+- For any single flow whose deterministic pre-split count ≥2 → STOP that flow's draft, route to `[[story-split]]`. Mark the flow as SPLIT RECOMMENDED in `flow-summary.md`. Continue with the other flows.
 
-5. **Visual inference confidence — single banner only.** Since the source IS Figma, the banner is always `**Source: Figma → values can be tokenized at implementation.**`. If MCP Figma is unavailable and the user falls back to PNG exports, switch the banner to raster (`pixel-derived, not token-confirmed`).
-
-6. **Sibling task IDs.** When the inventory phase produces multiple flows, ticket slugs follow rule F (naming pattern). Do NOT invent slugs without consulting `.storywright-context.json`.
-
-7. **Mockup chrome detection — closed list** (nav rail, top bar, footer, toast slot, modal scrim, app tabs). If a frame shows chrome that's NOT explicitly part of a flow, ask via `AskUserQuestion` whether it's a separate story, shared shell, or out-of-scope.
-
-8. **Anti-PRD is part of each story's INVEST `Small` criterion** — see `[[invest-checklist]]` Small.
-
-9. **Cross-skill context persistence.** Read `<output-folder>/.storywright-context.json` first (exact folder only). Write resolved answers back. Schema same as other v2.2 skills, plus:
-   ```json
-   {
-     "extra": {
-       "figma_url": "<url>",
-       "figma_scope": "file | page | frame",
-       "mcp_available": true | false
-     }
-   }
-   ```
-
-10. **Mechanical NxN dep matrix when emitting multiple stories (rule A).** If N>1 flows produce N stories, parse each story's `Given` lines for surface nouns owned by sibling flows. Mark `DEP(Sj → Si)` per match. Render the matrix in `flow-summary.md`. No intuition.
-
-11. **Per-story V audit (rule C).** For each candidate story, one-line test: "If only this story ships and no sibling flow exists, does a real user complete a real task?". If no → `WEAK · merge-upstream-candidate`. Recommend merging in `flow-summary.md`.
-
-12. **Passive-goal downstream prompt (rule G).** If a story's `I want to` verb is observational AND `so that` lacks downstream action → ask once via `AskUserQuestion`.
-
-### 4a. Language auto-detect — expanded signals (E)
-Same weighted table as refine/generate/split (Gherkin keywords, persona phrasing, column names, domain verbs, title). Plus Figma-specific signal: **frame names** and **layer text** in M = medium weight.
-
-### Rule F. Naming pattern — ask once, persist
-Same options. Persist in `naming_pattern` inside `.storywright-context.json`. Used for all story slugs in this run.
-
-### Rule D. Surface vs styling
-Same deterministic rule. A frame counts as a separate flow ONLY if it has its own user goal (verb where the user *does something*). A purely visual variant (color theme, light/dark) is NOT a new flow.
-
-## When to use
-
-- User pastes a Figma link.
-- User says "generate stories from this design".
-
-## Inputs & interpretation
-
-- **figma-link** — file URL, page URL, or specific frame URL. Detect the scope:
-  - File URL → consider the whole file; ask which page or flow to focus on
-  - Page URL → enumerate frames in that page
-  - Frame URL → single-screen analysis (usually one story)
+If N=1 (single frame URL) → standard single-story output. No `flow-summary.md`.
 
 ## Application (step-by-step)
 
+Follow the **base Application** skeleton for the front-end behaviors (context load, language with Figma signal weighting, persona, passive-goal, gap-check, siblings). Figma-specific steps:
+
 ### Phase 0 — MCP availability + context load
 
 1. Verify MCP Figma server is connected. See `mcp-figma-notes.md`.
-2. **Read prior context.** If `<output-folder>/.storywright-context.json` exists (exact folder only), load it.
-3. If MCP unavailable:
-   - Ask via `AskUserQuestion`: install MCP / export PNGs / paste textual flow descriptions.
-   - If user falls back to PNG, set `design_source = raster` in context file and use the raster banner per rule 5.
-
-### Phase 0.5 — Companion inputs + language
-
-1. Detect companion text or PNGs.
-2. Run language auto-detect (rule 4a). Adopt silently if signals agree; ask if split.
-3. Persona sharpening: if persona ambiguous, ask via `AskUserQuestion`.
+2. Read prior context per base rule 9.
+3. If MCP unavailable, ask via `AskUserQuestion` for fallback: (a) install MCP, (b) export PNGs, (c) paste textual flow descriptions. If user picks PNG, set `design_source = raster` in context and use the raster banner.
 
 ### Phase 1 — Inventory (MCP)
 
 1. List pages in the file (if MCP allows).
-2. For the target page, list frames with:
-   - Frame name
-   - Frame type (entry, modal, error state, empty state, success state, loading, etc.)
-   - Outgoing prototype links
-3. Identify **flows** by grouping frames connected by prototype links. One flow = one candidate story (or epic if large).
-4. Apply rule D: visual variants of the same flow do NOT count as new flows.
+2. For the target page, list frames with: frame name, frame type (entry/modal/error/empty/success/loading), outgoing prototype links.
+3. Identify **flows** by grouping frames connected by prototype links. One flow = one candidate story (or epic if pre-split count ≥2).
+4. Apply base rule D: visual variants of the same flow do NOT count as new flows.
 
 ### Phase 2 — Per-flow inference
 
 For each flow:
+1. Identify the user goal, entry point, states (empty/loading/success/error/edge).
+2. Score confidence per inference (HIGH/MEDIUM/LOW). Below HIGH → `⚠️ Assumed` inline.
+3. Run base rule G (passive-goal check) on the inferred goal.
+4. Run base deterministic pre-split counter on the flow.
+   - Count ≤1 → draft the base canonical block for this flow.
+   - Count ≥2 → mark flow as SPLIT RECOMMENDED; skip drafting.
 
-1. Identify the **goal** (what user outcome).
-2. Identify the **entry point**.
-3. Enumerate **states**: empty / loading / success / error / edge. Fold into AC failure paths (rule 3); do NOT emit an Edge Cases section.
-4. Identify **components** and their **inputs/outputs**.
-5. Score confidence per inference: HIGH / MEDIUM / LOW. Below HIGH → `⚠️ Assumed` inline.
-6. Run passive-goal check (rule G).
-7. Run pre-split deterministic counter (rule D) on the flow. If count ≥2 → recommend `[[story-split]]` for THAT flow before drafting.
-
-### Phase 3 — Draft canonical block per flow
-
-```markdown
-### [Flow Title]
-
-#### Use Case
-- **As a** [persona]
-- **I want to** [action]
-- **so that** [outcome with downstream action — rule G]
-
-#### Acceptance Criteria
-- **Scenario:** [single-outcome scenario name]
-- **Given:** [context — surface nouns drive flow-summary dep matrix]
-- **When:** [single trigger]
-- **Then:** [single observable outcome]
-
-#### Design Reference
-**Source: Figma → values can be tokenized at implementation.**
-- <frame URL or frame names>
-
-#### INVEST
-- I/N/V/E/S/T — one line each.
-- **Verdict:** READY | SPLIT RECOMMENDED | NEEDS REFINEMENT | NOT A STORY
-
-#### Generation log (≤3 lines)
-- Mapped from frames: <FRAME-IDs>; pattern: <if any>.
-```
+### Phase 3 — Draft canonical block per flow (count ≤1 flows only)
 
-### Phase 4 — Multi-flow analysis (if N>1)
+Use the base canonical output shape. Design Reference banner per source-specific differential above.
 
-1. **Mechanical NxN dep matrix (rule 10).** Parse each story's Given lines for surface nouns owned by sibling flows. Emit in `flow-summary.md`.
+### Phase 4 — Multi-flow analysis (N>1)
 
-2. **Per-story V audit (rule 11).** Flag merge-upstream candidates loudly.
-
-3. **Coherence check** — verify the union of stories covers the user journey shown in Figma. Flag gaps.
+1. **Mechanical NxN matrix (base rule 10).** Parse each story's Given lines.
+2. **Per-story V audit (base rule 11).** Flag merge-upstream candidates.
+3. **Coherence check.** Union of stories covers the journey shown in Figma.
 
 ### Phase 5 — Output
 
-For each story:
+Per drafted flow:
 - `story-<N>.standard.md` + `story-<N>.jira-wiki.md`.
 
-Plus single `flow-summary.md`:
-```markdown
-### Flow Summary — <Figma file/page>
-
-| # | Story | Frames | INVEST verdict | V audit |
-|---|---|---|---|---|
-| 1 | login-google-web | AUTH-001, AUTH-002 | READY | PASS |
-| 2 | login-google-mobile | AUTH-101 | READY (after #1) | PASS |
-| 3 | recovery-flow | AUTH-201..AUTH-212 | SPLIT RECOMMENDED | — |
-
-**Dependency matrix (rule 10):**
-
-|     | #1 | #2 | #3 |
-|-----|----|----|----|
-| #1  | —  |    |    |
-| #2  |DEP | —  |    |
-| #3  |    |    | —  |
+If N>1 OR any flow was routed to split:
+- `flow-summary.md` with the matrix, V audit, build order, and SPLIT-RECOMMENDED markers.
 
-**Build order:** #1 → #2 (parallel: #3 after its own split).
-
-**Design source:** Figma (or raster, if PNG fallback).
-```
-
-Plus `.storywright-context.json` updated.
+Plus `.storywright-context.json` updated (`extra.figma_url`, `extra.figma_scope`, `extra.mcp_available`).
 
 NO `clarifications.md`. NO Edge Cases sections. NO NFR blocks. NO per-claim visual tags.
 
@@ -194,51 +100,47 @@ NO `clarifications.md`. NO Edge Cases sections. NO NFR blocks. NO per-claim visu
 ### Good
 Input: Figma file URL with 3 flows on the "Auth" page (login, signup, password reset).
 Output:
-- 3 canonical stories.
+- 3 canonical stories (one per flow).
 - `flow-summary.md` with mechanical matrix (#2 DEP #1; #3 independent).
 - V audit: all PASS.
-- Recovery flow has 12 frames → pre-split counter ≥2 → recommend `[[story-split]]` for #3 only.
+- Recovery flow has 12 frames → pre-split counter ≥2 → marked SPLIT RECOMMENDED; not drafted.
 
 ### Good — PNG fallback
-MCP unavailable. User exports 3 PNGs. Skill switches banner to raster, marks `design_source = raster`, generates 3 stories with `[mockup-pixel-derived]`-style inheritance (single banner per Design Reference).
+MCP unavailable. User exports 3 PNGs. Skill switches banner to raster, marks `design_source = raster`, generates 3 stories with single raster banner each.
 
 ### Good — passive goal fires
-Flow goal inferred as "view dashboard". Skill detects passive verb → asks: "What does the user do with the dashboard data?". User: "Spot anomalies and drill into them." So-that strengthened.
+Flow goal inferred as "view dashboard". Base rule G fires. Ask: "What does the user do with the dashboard data?". User: "Spot anomalies and drill in." So-that strengthened.
 
 ### Bad
 One story per frame. Frames are screens; stories are user goals.
 
 ### Bad
-Emitting `clarifications.md`. Violates rule 1.
+Emitting `clarifications.md` (violates base rule 1).
 
 ### Bad
 Skipping the mechanical matrix in `flow-summary.md` when N>1.
 
-## Common Pitfalls
+## Common Pitfalls (figma-specific)
 
 - Treating each frame as a story.
 - Skipping prototype-link analysis — without flow structure, user goals are guesses.
-- Ignoring empty/error/loading states. Designers usually include them; fold into AC failure paths.
+- Ignoring empty/error/loading states. Fold into AC failure paths, not edge-case sections.
 - Trusting MEDIUM/LOW inferences silently — mark `⚠️ Assumed`.
-- Generating stories without verifying coverage of all error paths.
-- Skipping per-story V audit (rule 11) — figma flows are easy to over-split.
-- Re-asking questions already in `.storywright-context.json`.
-- Tagging every visual claim instead of using the single Figma banner.
+- Skipping per-story V audit when N>1 (figma flows over-split easily).
+- All other pitfalls in `[[storywright-base]]` apply equally.
 
 ## References
 
+- [[storywright-base]] — the rulebook
 - [[story-generate]]
-- [[story-split]]
 - [[story-refine]]
-- [[clarification-questions]]
+- [[story-split]]
 - `./mcp-figma-notes.md` (MCP server setup)
 
 <claude-specific>
+- Read `[[storywright-base]]` before applying. Do not duplicate its rules in your reasoning.
 - Use Claude vision when MCP is unavailable and the user drops PNGs.
 - Use extended thinking for flow grouping — prototype links can be ambiguous.
-- Cache the Phase 2 inference checklist across calls.
-- When MCP Figma is available, batch frame metadata fetches into one round trip.
-- Read `.storywright-context.json` ONLY from the exact target output folder.
-- Build the multi-story dependency matrix from Given-text parsing (rule 10), not intuition.
-- Never call Write for any sidecar question file. Use `AskUserQuestion`.
+- When MCP is available, batch frame metadata fetches into one round trip.
+- Build the multi-story dependency matrix from Given-text parsing (base rule 10), not intuition.
 </claude-specific>