@pavp/storywright 1.5.0 → 1.6.1

package/skills/story-generate/SKILL.md

@@ -1,172 +1,96 @@
 ---
 name: story-generate
-description: Transform an ambiguous prompt, half-baked story, screenshot, or Figma link into a Jira-ready user story with acceptance criteria, DoD, edge cases, and risks. Ask only critical clarifying questions.
+description: Transform an ambiguous prompt, half-baked story, screenshot, or Figma link into a Cohn+Gherkin user story. Inherits all hard rules from storywright-base.
 trigger: "/story-generate | generate a user story | write a user story | turn this into a story | crear historia de usuario"
-intent: Top-level orchestrator skill that drives the full story generation flow by composing component skills.
-version: 1.0.0
+intent: Top-level orchestrator that drafts a fresh story from any input. Behavior 100% identical to siblings except for source (raw / ambiguous input) and split-behavior (recommend /story-split when pre-split count ≥2).
+version: 2.3.0
 inputs:
   - text
   - image
   - figma-link
 outputs:
-  - story.jira-wiki.md
   - story.standard.md
-  - clarifications.md
+  - story.jira-wiki.md
+  - .storywright-context.json
 composes:
+  - _components/storywright-base
   - _components/clarification-questions
   - _components/acceptance-criteria
   - _components/invest-checklist
-  - _components/definition-of-done
-  - _components/business-rules
-  - _components/edge-cases
-  - _components/analytics-events
-  - _components/risks-and-dependencies
   - _components/jira-wiki-formatter
 ---
 
 ## Purpose
 
-Take whatever the PM has — a one-liner, a half-baked story, a screenshot, a Figma link — and produce a story that an engineer can pick up and ship without follow-up questions. Always output two artifacts (Jira wiki + CommonMark).
-
-## When to use
-
-- The user has a goal but not a story (e.g., "Permitir login con Google").
-- The user pastes a vague story and wants it production-ready.
-- The user drops an image/Figma link and asks for stories.
-
-## Inputs & how to interpret each
+Take whatever the PM has — a one-liner, a half-baked story, a screenshot, a Figma link — and produce a Cohn+Gherkin story an engineer can pick up and ship without follow-up questions.
 
-### Text prompts
-Anything from a single phrase to a paragraph. If the prompt names only a feature, infer the implicit user goal.
+**All hard rules, canonical output shape, language detection, mechanical pre-split test, context persistence, terminal-only Q, and INVEST handling live in `[[storywright-base]]`. Read that first. Anything in this file is a SOURCE-SPECIFIC or SPLIT-BEHAVIOR delta only.**
 
-### Local images (PNG/JPG)
-Use vision. Extract:
-- UI elements (buttons, fields, navigation)
-- Visible states (loading, error, success)
-- Inferred flow (what does each element trigger?)
-- Confidence per inference (high / medium / low). Anything below high → add `> ⚠️ Assumed:` blockquote in the output and surface in clarifications.
+## Source-specific differential
 
-### Figma links
-If MCP Figma is available (see `[[story-from-figma]]`), use it to enumerate frames, components, navigation. If not, fall back to asking the user to drop screenshots.
+- **Source:** raw / ambiguous text, optionally fused with screenshot and/or Figma URL.
+- **What changes vs base:** at intake the prompt may name only a feature; infer the implicit user goal via rule 3 (persona sharpening) + rule G (passive-goal check) of the base. Mixed inputs follow the base conflict-detection rule plus the source-priority table below.
 
-### Mixed inputs (text + image + Figma)
-
-The skill is designed to **fuse multiple sources** in a single invocation. Common pairings:
-
-- **Text + screenshot** — text states the goal, image shows the proposed UI. Use text for `User Story / Goal / Scope`, image for `Components / States / Edge cases / UX flow`.
-- **Text + Figma link** — text gives intent, Figma gives implementation surface. Use text for `User Story / Business goal`, Figma for `Technical considerations / Edge cases / Components / Multi-screen flows`.
-- **Text + image + Figma** — full triangulation. Highest fidelity; also highest chance of conflict.
-
-**Source priority (when sources disagree):**
+### Mixed-input source priority (text + image + Figma)
 
 | Section | Primary | Secondary | Tertiary |
 |---|---|---|---|
-| User Story / Goal | Text | Figma (frame titles, callouts) | Image |
-| Business Rules / Scope | Text | Figma | Image |
+| User Story / Goal | Text | Figma frame titles | Image |
+| Scope | Text | Figma | Image |
 | UI Components / States | Figma | Image | Text |
-| Edge Cases | Figma + Image (states shown) | Text | — |
-| Technical Considerations | Figma (component naming, design system refs) | Text | Image |
-| Acceptance Criteria | Triangulate all three | — | — |
+| AC observable outcomes | Triangulate | — | — |
+
+Conflicts → BLOCKING `AskUserQuestion` per base rule 1.
+
+## Split behavior differential
 
-**Conflict handling:**
+If the base **deterministic pre-split test** returns count ≥2:
+- **STOP drafting.**
+- Output a terminal message listing candidate children + per-pair dep notes (base rule 10) + V audit (base rule 11).
+- Recommend `/story-split` to the user.
+- Do NOT auto-split, do NOT produce a 15-section story.
 
-1. **Detect the conflict explicitly.** Example: text says "Google only" but Figma shows Google + Facebook buttons.
-2. **Do NOT silently pick a winner.** Surface the conflict in `clarifications.md` as a BLOCKING question: *"Text says X but design shows Y — which is canonical?"*
-3. **If the user is in-session, ask immediately** before drafting. If running batch, mark the story `DRAFT` and write both options in scope/out-of-scope with `> ⚠️ Conflict:` annotation.
-4. **Scope coverage check:** if Figma shows N flows but text describes 1, ask whether to (a) generate 1 story bounded to text, (b) generate N stories from Figma, or (c) generate 1 story + flag remaining flows as roadmap.
+If count ≤1:
+- Proceed with the base step-by-step Application skeleton (read context → language → persona → passive-goal → gap-check → siblings → fill canonical block → INVEST → render).
 
 ## Application (step-by-step)
 
-1. **Detect input types present** — text, image, figma-link, or any combination. Branch accordingly:
-   - **Single source** → process as before.
-   - **Mixed sources** → run the "Mixed inputs" protocol above, including source-priority lookup and explicit conflict detection BEFORE drafting.
-2. **Intake gap check** — invoke `[[clarification-questions]]`. If it returns BLOCKING questions, **ask first** before drafting.
-3. **Detect language** of input (es | en | other). Output in the input language.
-4. **Draft skeleton** of the structured story (all 15 sections from the template).
-5. **Fill the CORE first** (always required, in order):
-   1. **Title** — concise, ≤8 words.
-   2. **Summary** — single value-focused sentence ("Enable Google login for trial users to reduce signup friction"), NOT a feature label ("Add Google button"). Elevator pitch.
-   3. **User Story** (As a / I want to / so that).
-      - **Persona check:** if role is "user" or "customer", push for sharper ("trial user", "Workspace admin"). Generic personas hide motivation.
-      - **"So that" check:** outcome must be distinct from action. "So I can save my work" = restating; "So I don't lose progress if tab crashes" = real motivation.
-   4. **Acceptance Criteria** via `[[acceptance-criteria]]` — at minimum the happy path + one failure mode.
-   5. **Definition of Done** via `[[definition-of-done]]`.
-
-6. **Fill OPTIONAL sections only if they have real content.** Drop any that would be empty or boilerplate:
-   - Contexto / Business goal — include when there's a stated trigger or KPI
-   - Scope / Out of scope — include when boundaries are non-obvious
-   - `[[business-rules]]` — include when invariants exist beyond the ACs
-   - Technical considerations — include when surface/SDK/flag matters
-   - `[[edge-cases]]` — include when ≥3 high-impact edges exist
-   - `[[analytics-events]]` — include when story has measurable funnel
-   - `[[risks-and-dependencies]]` — include when there are real blockers or unknowns
-
-   The bias is **less is more**. A clean 4-section story beats a 15-section one full of `N/A`.
-6. **Run INVEST self-check** via `[[invest-checklist]]`:
-   - `READY` → continue.
-   - `NOT A STORY` (V failed) → STOP. Tell the user this is a tech task, not a user story. Suggest reframing or combining with user-facing work.
-   - `NEEDS REFINEMENT` (T or N failed) → revise the failing sections in place.
-   - `RUN A SPIKE` (E failed on unknowns) → recommend a 1–2 day investigation; do not split or generate yet.
-   - `SPLIT RECOMMENDED` (I, E, or S failed) → STOP. Hand off to `[[story-split]]`. **Never auto-split.**
-7. **Render outputs** via `[[jira-wiki-formatter]]`:
-   - `story.jira-wiki.md` — Jira wiki markup
-   - `story.standard.md` — CommonMark
-8. **If clarifications remain unresolved** (user skipped them, or low-confidence visual inferences exist):
-   - Emit `clarifications.md` with the outstanding questions
-   - Mark the story output with a `DRAFT` banner at the top
-   - Tell the user explicitly what would unblock promoting from DRAFT to READY
-9. **Present both artifacts** as fenced code blocks. Ask the user whether to save to disk (offer paths under `./stories/<slug>/`).
+Follow the **base Application** skeleton exactly. The only override is step 7's split branch (above): on count ≥2, route to `/story-split` recommendation instead of host-side recursion.
 
 ## Examples
 
 ### Good — text prompt
 Input: *"Permitir login con Google"*
+- Language auto-detect → ES.
+- Persona sharpening → ask: trial user? admin? signed-out visitor?
+- Pre-split count = 1 (one auth flow). Continue.
+- Draft canonical block; INVEST → READY. Render.
 
-Flow:
-1. Run gap check → 3 BLOCKING questions: scope of accounts, account linking, surface (web/mobile/both).
-2. Ask the 3 questions, wait for answers.
-3. Draft + fill all 15 sections.
-4. INVEST → `READY`.
-5. Render both outputs.
-6. Done.
-
-### Good — image input
-Input: screenshot of a dashboard with a filter sidebar.
-
-Flow:
-1. Vision: extract filter categories, infer apply/reset actions.
-2. Confidence on "filters persist across navigation" → MEDIUM → mark as `⚠️ Assumed` and surface in clarifications.
-3. Run gap check → 1 BLOCKING (does this replace or augment current filters?).
-4. Ask, draft, fill, INVEST, render.
-
-### Bad
-
+### Good — broad input routed to split
 Input: *"Build the new dashboard"*
+- Pre-split count ≥2 → STOP. Terminal message: candidate children + dep notes + V audit + "Run `/story-split`".
+- No drafted story written.
 
-Don't draft. The scope is too broad. Run gap check → propose splitting into smaller stories at the **clarification step**, before the story is drafted. (Effectively delegates to `[[story-split]]` upfront.)
+### Good — passive goal fires
+Input: *"As a user, I want to view list of customers, so that I find details."*
+- Rule G fires. Ask: "What does the user do with the customer they find?"
+- User: "Call them." → so-that strengthened.
 
-## Common Pitfalls
+### Bad
+Writing any sidecar question file (violates base rule 1).
 
-- Drafting before asking the critical questions. Always run intake first.
-- Ignoring confidence in image inferences. If you guessed, say so.
-- Auto-splitting. Never. Propose, wait, then split.
-- Mixing English and Spanish in the output. Pick the input language.
-- Skipping the `clarifications.md` file when assumptions remain.
+### Bad
+Drafting a 15-section story when pre-split count ≥2 (violates split behavior differential).
 
 ## References
 
-- [[story-refine]] (use when input is an existing story to improve)
-- [[story-split]] (use when INVEST fails on Independent/Estimable/Small)
-- [[story-from-figma]] (use when input is a Figma link)
-- [[clarification-questions]]
-
-## Output templates
-
-See `templates/story.jira-wiki.md` and `templates/story.standard.md` in this skill's folder for the canonical section ordering and formatting.
+- [[storywright-base]] — the rulebook
+- [[story-refine]] (when input is an existing story)
+- [[story-split]] (when count ≥2)
+- [[story-from-figma]] (when input is Figma URL)
 
 <claude-specific>
-- Use extended thinking for INVEST check and for vision confidence scoring.
-- Cache the 15-section taxonomy and component invocation order across calls.
-- When input includes images, attach them to the same message as the prompt to use Claude's native vision (do not describe-then-reason in two steps).
-- Use prompt caching on the component skill bodies (they're long and reused).
+- Read `[[storywright-base]]` before applying. Do not duplicate its rules in your reasoning.
+- For mixed inputs, attach images in the same message for native vision.
+- Use extended thinking for INVEST and pre-split counting.
 </claude-specific>

package/skills/story-refine/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: story-refine
-description: Audit an existing user story and fix it in place. Cohn+Gherkin canonical output. Asks clarifications ONLY in terminal. Recommends split when story has multiple outcomes.
+description: Audit an existing user story and fix it in place. Cohn+Gherkin canonical. Inherits all hard rules from storywright-base.
 trigger: "/story-refine | refine this story | improve this story | refinar historia | this story is incomplete"
-intent: Refinement skill for stories that already exist but are incomplete or weakly specified. Default philosophy = Mike Cohn (story is a conversation starter, not a spec). Splits aggressively. Never produces mini-PRDs.
-version: 2.2.0
+intent: Refinement skill for stories that already exist but are incomplete or weakly specified. Behavior 100% identical to siblings except for source (existing story text) and split-behavior (recommend /story-split when pre-split count ≥2).
+version: 2.3.0
 inputs:
   - text
   - image
@@ -13,6 +13,7 @@ outputs:
   - story.jira-wiki.md
   - .storywright-context.json
 composes:
+  - _components/storywright-base
   - _components/clarification-questions
   - _components/acceptance-criteria
   - _components/invest-checklist
@@ -21,292 +22,81 @@ composes:
 
 ## Purpose
 
-Bring an existing user story up to standard *without* turning it into a feature spec. Output is conversation-ready, Cohn-format, Gherkin AC. If the story is too big, recommend split — do not refine an oversized story into a longer one.
+Bring an existing user story up to standard *without* turning it into a feature spec.
 
-## Hard rules (no exceptions)
+**All hard rules, canonical output shape, language detection, mechanical pre-split test, context persistence, terminal-only Q, mechanical NxN dep matrix, per-child V audit, 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. All gap questions go through `AskUserQuestion` (batch in groups of ≤4). If a gap is non-blocking, mark `⚠️ Assumed` inline in the story body — do not ask.
+## Source-specific differential
 
-2. **Cohn + Gherkin canonical.** One Use Case block. One AC scenario per story (one Given chain, one `When`, one `Then`). If the story naturally needs >1 `When`/`Then` → **STOP refining, recommend `/story-split`**.
+- **Source:** an existing user story (text). May be vague, missing sections, or have hand-wavy ACs.
+- **What changes vs base:**
+  - **Preserve original wording** where it was already good. Refine is NOT regenerate — if the PM already wrote a sharp persona / goal / so-that, do not rephrase it.
+  - **Don't renumber ACs** the team may already reference externally. Append new content, don't shuffle.
+  - **Detect which sections are present / missing / weak** before applying the base canonical block. Fill only what's weak; leave good sections alone.
+  - If companion image / Figma is attached, base conflict-detection applies. Story text is canonical for `User Story / Scope / Business value`; image/Figma is canonical for `component names / observable states` referenced in AC.
 
-3. **No mini-PRDs.** The following sections are PROHIBITED in story output (they belong to DoD, design handoff, or sibling tickets):
-   - Non-Functional Requirements blocks (a11y/i18n/perf/tokens) — these live in the team's global Definition of Done
-   - Edge Cases enumerations — sibling stories or DoD
-   - Dependencies as prose — use Jira ticket links instead
-   - Visual specs derived from raster mockups (pixel measurements, hex inferences) inline with each claim
-   - Refinement logs >3 lines (>5 if verdict is SPLIT RECOMMENDED)
+## Split behavior differential
 
-4. **Output language matches the user's chat language**, not the story's. Auto-detect first (see rule 4a); only ask via `AskUserQuestion` if detection is ambiguous.
+If the base **deterministic pre-split test** returns count ≥2:
+- **STOP refining.**
+- Output a terminal message listing candidate children + per-pair dep notes (base rule 10) + V audit (base rule 11).
+- Recommend `/story-split` to the user.
+- Do NOT produce an oversized refined story.
 
-5. **Visual inference confidence — single banner only.** Do NOT tag every visual claim. Instead, add ONE banner at the top of the Design Reference block declaring the source type. All claims under that block inherit the banner's confidence level.
-   - Raster source (PNG/JPG) → banner: `**Source: raster mockup → all visual specs are pixel-derived, not token-confirmed.**`
-   - Figma source → banner: `**Source: Figma → values can be tokenized at implementation.**`
-   - Design-token source → banner: `**Source: design tokens → values are authoritative.**`
-   - Never assert hex values, pixel sizes, or exact spacing from raster without the raster banner.
-
-6. **Sibling task IDs.** If story body references "next task", "future task", "another story", "siblings" — check `<output-folder>/.storywright-context.json` first (rule 9). If unresolved, ask via `AskUserQuestion`. If user has none yet, leave a `TODO: link sibling` placeholder, do not invent (unless rule F applies — see below).
-
-7. **Mockup chrome detection — closed list.** Chrome = exactly these elements:
-   - left nav rail / sidebar
-   - top bar (user menu, global breadcrumbs, global search)
-   - footer
-   - persistent toast/snackbar slot
-   - persistent modal scrim
-   - app-level tabs
-
-   If companion image shows any of the above and the story body does not mention them, ask via `AskUserQuestion` whether each one 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]]` step 7 — line count ceiling lives inside the `Small` criterion so there is one source of truth.
-
-9. **Cross-skill context persistence.** When the skill resolves any clarification via `AskUserQuestion`, write the **answers** to `<output-folder>/.storywright-context.json`. This is NOT a question file — it is a resolved-answers file. 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-refine",
-     "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": "<see rule F>",
-     "extra": {}
-   }
-   ```
-   Future skills (`story-split`, `story-from-figma`, etc.) MUST read this file before re-asking the same questions.
-
-10. **Children independence — mechanical detection (A).** When the skill recommends or executes split, build an NxN dependency matrix MECHANICALLY, not by intuition:
-    - For each child Cj, parse its `Given:` and `and Given:` lines.
-    - If any `Given` text contains a surface noun owned by child Ci (e.g., Cj's Given mentions "the grid" and Ci's title/scope owns "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 lists explicit build order derived from the matrix (topological).
-    - Independence-by-intuition is forbidden. If a dep is real but no Given mentions it, rewrite the child's Given to make it explicit, then re-run the match.
-
-11. **Per-child V audit (C).** After split, for each candidate child run a one-line V test: "If only this child ships and no sibling exists, does a real user complete a real task?". If the answer is "no, useless until <other child> ships" → mark V as `WEAK · merge-upstream-candidate` and recommend merging that child into its parent surface instead of keeping it standalone. Do not let stylistic/UI-fragment children survive the split.
-
-12. **Passive-goal downstream prompt (G).** If the story's `I want to` verb is passive/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 data?". Use the answer to strengthen the `so that` clause. This forces explicit value. Skip the prompt if `so that` already names a downstream action (e.g., "so that I can call the customer").
-
-### 4a. Language auto-detect — expanded signals (E)
-
-Run cheap detection before asking. Look at multiple signals, not just Gherkin keywords:
-
-| 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", "submitting" vs "enviar") | AC bullets | medium |
-| Title language | header | low |
-
-**Decision:**
-- All high+medium signals agree on language M → adopt M silently. No question. Mark inline `⚠️ Assumed: output language = <M> (auto-detected from <signals>)`.
-- Signals split (some EN, some ES) → ask once via `AskUserQuestion`.
-- User-chat language = L, story-body signals = M, but high signals tie → prefer M (story body is contract).
-
-Persist via rule 9.
-
-### Rule F. Naming pattern — ask once, persist
-
-When the skill needs to invent a tentative ticket slug (e.g., for sibling references with no IDs yet) 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" (assume next available)
-```
-
-Persist the answer in `.storywright-context.json` under `naming_pattern`. Use it for all sibling slugs in the current run AND future skills reading the same context file.
-
-## When to use
-
-- User pastes an existing story (text) and asks to make it Jira-ready.
-- A story has ACs but no testable outcomes.
-- INVEST gate fails on `Testable` or `Negotiable` — fixable in place (not splittable).
-
-For oversized stories that fail `Independent / Estimable / Small`, OR have multiple `When`/`Then` pairs, OR have >1 distinct outcome (per the deterministic counter below) → hand off to `[[story-split]]` instead.
-
-## Inputs & interpretation
-
-- **text** — existing story. Detect which sections are present, which are missing, which are weak.
-- **image (optional)** — companion screenshot/mockup. Use to validate UI claims only. NEVER as source for pixel-precise visual specs inline with each AC claim (see rule 5).
-- **figma-link (optional)** — companion design. Use to enrich AC observable outcomes (states, named components).
-
-### Mixed inputs source-priority
-
-- Story text canonical for `User Story / Scope / Business value`.
-- Image/Figma canonical for `component names / observable states` referenced inside AC.
-- Conflicts → BLOCKING `AskUserQuestion`. Never silently rewrite the story to match the design.
-
-## Canonical output shape (this is the WHOLE story)
-
-```markdown
-### [Title]
-
-#### Use Case
-- **As a** [persona]
-- **I want to** [action]
-- **so that** [outcome with downstream action — see 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 A]
-- **and Given:** [context]
-- **When:** [single trigger]
-- **Then:** [single observable outcome]
-
-#### Design Reference (optional)
-**Source: <raster | figma | tokens> → <inherited-confidence banner from rule 5>**
-- [link or path]
-- visual notes: [...]
-
-#### INVEST
-- I/N/V/E/S/T — one line each, evidence-based.
-- **Verdict:** READY | SPLIT RECOMMENDED | NEEDS REFINEMENT | NOT A STORY
-
-#### Refinement log (≤3 lines; ≤5 if verdict=SPLIT)
-- ...
-```
-
-Nothing else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No Assumptions block (assumptions get `⚠️ Assumed` inline or are resolved via `AskUserQuestion`).
+If count ≤1:
+- Proceed with the base step-by-step Application skeleton, applying the source-specific preservation rules above.
 
 ## Application (step-by-step)
 
-0. **Detect companion sources** (image, figma-link). Run conflict detection against story text. Run chrome-detection using the closed list in rule 7. Surface conflicts as BLOCKING `AskUserQuestion` calls.
-
-1. **Parse story** into the canonical sections above. Note: present / missing / weak.
-
-2. **Read prior context.** If `<output-folder>/.storywright-context.json` exists (exact folder only — no sibling fallback), load it. Apply resolved answers; skip the corresponding questions.
-
-3. **Language resolution (rule 4 + 4a).** Auto-detect using the expanded signal table. Ask only if signals split. Persist via rule 9.
-
-4. **Passive-goal check (rule G).** If `I want to` verb is observational AND `so that` lacks downstream action → ask once. Persist resolution into the strengthened `so that` clause.
-
-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 (rule 6).** If found and unlinked → ask via `AskUserQuestion` once. If user opts for tentative slugs, apply rule F (naming pattern). Persist via rule 9.
-
-7. **Deterministic pre-split test.** Apply this counter mechanically — do not eyeball:
-
-   **Count = sum of all hits below:**
-   | Signal | Hit value |
-   |---|---|
-   | AC bullet starting with an action verb at the 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 — see (D) below for what counts | +1 each |
-
-   **(D) Surface vs styling rule (deterministic).** A "named UI surface" counts as +1 ONLY if it has its own user goal — meaning there is a verb in the story body 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, background, padding, alignment) 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 background)" — styling of grid → 0
-   - "pagination control with page numbers and arrows" — surface with user goal (navigating) → +1
-   - "5 columns: Code, Customer name, Phone, Email, Address" — columns are sub-components of grid → 0 (grid still counts once)
-   - "results counter next to search button" — surface with user goal (reading count) → +1
-
-   **Do NOT count:**
-   - sub-bullets describing the same flow (column names inside one grid = the grid itself, not separate outcomes)
-   - styling of an existing surface (header purple = part of grid, not a new outcome)
-   - preconditions or "rendered" statements (passive layout assertions are not Whens)
-
-   **Decision:**
-   - Count ≤1 → continue to step 8.
-   - Count ≥2 → **STOP. Recommend `/story-split` via terminal message.** Output: list of candidate children + per-pair dependency note (rule 10) + V audit per child (rule 11).
-
-8. **Fill the weak sections** using `[[acceptance-criteria]]` (single Gherkin block) and `[[invest-checklist]]`. Preserve original wording where it was already good.
-
-9. **Run INVEST** via `[[invest-checklist]]` (which embeds the anti-PRD line-count check inside `Small` — rule 8).
-   - `READY` → render.
-   - `SPLIT RECOMMENDED` → STOP, recommend split (and run rule 10 children-independence matrix + rule 11 V audit per child).
-   - `NEEDS REFINEMENT` → iterate failing dimension, max 1 cycle, then STOP.
-   - `NOT A STORY` → tell user it's a tech task and stop.
-
-10. **Render** both outputs via `[[jira-wiki-formatter]]`. Files: `story.standard.md` + `story.jira-wiki.md`. Plus `.storywright-context.json`. No other files.
-
-11. **Refinement log** ≤3 bullets (≤5 if SPLIT) appended at story end.
+Follow the **base Application** skeleton exactly. Refine-specific behavior:
+- Step 5 (gap-check): only fill **weak/missing** sections; leave sharp sections alone.
+- Step 7 (pre-split test): on count ≥2 → STOP refining, route to `/story-split` recommendation.
+- Step 11 (log): label as "Refinement log".
 
 ## Examples
 
 ### Good — READY
 Input: story with title + Use Case + 2 vague ACs.
-Output: canonical block, ≤30 lines, AC tightened to single Given/When/Then, INVEST verdict READY, ≤3-line refinement log, `.storywright-context.json` written.
-
-### Good — SPLIT (Spanish)
-Input: historia con 7 bullets de AC (grilla + contador + paginación + link).
-Output: NO refined story. Mensaje terminal:
-```
-SPLIT RECOMMENDED. Conteo determinístico = 4 (grilla, contador, paginación, link).
-Children candidatos:
-1. Page shell + chrome (si in-scope)
-2. Grid 5 columnas + header style
-3. Contador de resultados
-4. Control de paginación
-5. Link affordance en customer name
-Matriz independencia (parse mecánico de Given):
-- C4.Given menciona "the grid" → DEP(C4 → C2) → PARTIAL
-- C5.Given menciona "the grid" → DEP(C5 → C2) → PARTIAL
-- Orden build: C1 → C2 → {C3, C4, C5}
-V audit per child:
-- C1: PASS (chrome funcional = workspace context)
-- C2: PASS (read records)
-- C3: WEAK · merge-upstream-candidate — counter sin grid no entrega valor
-- C4: PASS (navigate pages)
-- C5: PASS (link affordance)
-Corré /story-split para expandir; considera mergear C3 en C2.
-```
+- Pre-split count = 1.
+- Tighten ACs to single Given/When/Then. Leave Use Case alone (was good).
+- INVEST → READY. ≤3-line Refinement log. Render.
 
-### Good — passive-goal prompt fires
-Input: "As a user, I want to view list of customers, so that I quickly find details."
-Skill detects passive verb `view` + thin `so that`.
-Asks: "What does the user do with the customer they find?"
-User: "Call them to schedule a service."
-Refined `so that`: "so that I can quickly find a customer and call them to schedule a service."
+### Good — SPLIT
+Input: story with 7 AC bullets (grid + counter + pagination + link).
+- Pre-split count = 4 (grid, counter, pagination, link).
+- STOP. Terminal message: candidate children + dep notes + V audit + "Run `/story-split`".
+- No refined story written.
 
-### Bad
-Adding NFR / a11y / i18n / Dependencies sections "to be thorough". Violates rule 3.
-
-### Bad
-Writing any sidecar question file instead of asking via `AskUserQuestion`. Violates rule 1.
+### Good — passive goal fires
+Refining: *"As a user, I want to view list of customers, so that I find details."*
+- Rule G of base fires. Ask: "What does the user do with the customer they find?"
+- User: "Call them." → strengthen so-that.
 
 ### Bad
-Tagging every visual claim with `[mockup-pixel-derived]` instead of using the single banner. Violates rule 5.
+Treating refine like generate — restating the user goal when the PM already wrote it.
 
 ### Bad
-Claiming 5 children all `Independent` after split without running the mechanical matrix from rule 10.
+Renumbering AC bullets the team may already reference.
 
 ### Bad
-Counting "header row purple" as +1 in the pre-split test. It is styling of the grid (rule D), not a separate surface. Should be 0.
+Producing a 400-line refined story (violates base rule 3 + INVEST Small ceiling).
 
-## Common Pitfalls
+## Common Pitfalls (refine-specific)
 
-- Treating refine like generate. If the PM already wrote the user goal, don't restate it.
-- Renumbering ACs — append new content, don't shuffle.
-- Skipping the deterministic pre-split test (step 7). Refining oversized stories produces oversized refined stories.
-- Eyeballing outcome counts or dep matrix instead of running the mechanical rules (D, A).
-- Re-asking questions already answered in `.storywright-context.json`.
-- Letting weak-V children survive the split (rule 11).
-- Skipping the downstream-action prompt for passive goals (rule G).
+- Rewriting good content. If a section is sharp, leave it.
+- Renumbering ACs. Append, don't shuffle.
+- Skipping the base pre-split test (step 7) — refining an oversized story produces an oversized refined story.
+- All other pitfalls listed in `[[storywright-base]]` apply equally.
 
 ## References
 
-- [[story-generate]]
-- [[story-split]]
-- [[invest-checklist]]
-- [[acceptance-criteria]]
+- [[storywright-base]] — the rulebook
+- [[story-generate]] (when input is ambiguous, not an existing story)
+- [[story-split]] (when count ≥2)
+- [[story-from-figma]] (when input is Figma URL)
 
 <claude-specific>
-- Diff the original sections against the refined ones in your reasoning; only emit changes that materially improve the story.
-- Never call Write for any question/clarification sidecar file. Use `AskUserQuestion`.
-- Treat step 7 (deterministic pre-split test) as a hard gate; do not skip even when the user explicitly asks to refine.
-- Read `.storywright-context.json` ONLY from the exact target output folder. Do not search siblings or parents.
-- After split, build the dependency matrix from Given-text parsing (rule 10), not intuition.
-- After split, run V audit per child (rule 11) and flag merge-upstream-candidates loudly.
-- For passive `I want to` verbs, fire rule G prompt before INVEST.
+- Read `[[storywright-base]]` before applying. Do not duplicate its rules in your reasoning.
+- Diff the original sections against the refined ones; only emit changes that materially improve the story.
+- Use extended thinking when running the base pre-split counter.
 </claude-specific>