@pavp/storywright 1.16.0 → 1.18.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "storywright",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "PM skills for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
   "author": "pavp",
   "license": "MIT",
@@ -21,7 +21,8 @@
     "skills/_components/edge-cases",
     "skills/_components/analytics-events",
     "skills/_components/risks-and-dependencies",
-    "skills/_components/story-formatter"
+    "skills/_components/story-formatter",
+    "skills/_components/estimation"
   ],
   "commands": [
     "commands/story-generate.md",

package/package.json

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

package/skills/_components/estimation/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: estimation
+description: Estimate a user story in Fibonacci story points using a deterministic weighted formula calibrated on real goldens. Output lives in story.dev.md only.
+trigger: "internal use by story-* skills"
+intent: Component skill that computes a Fibonacci story-point estimate from six countable signals (ACs, edge cases, dependencies, high-severity risks, business rules, INVEST E verdict). Produces ## Estimate in story.dev.md only — never in PM files.
+version: 1.0.0
+inputs:
+  - story-context
+outputs:
+  - estimate-block (dev.md only)
+---
+
+## Purpose
+
+Estimation gives the team a planning anchor grounded in story complexity signals — not gut feel or velocity. This component reads six structural signals from the completed story drafts and the INVEST result, runs a deterministic weighted formula, maps the raw score to a Fibonacci bucket, then allows a bounded ±1 LLM adjustment when a named signal justifies it.
+
+Output lives **exclusively** in `story.dev.md`. PM files (`story.standard.md`, `backlog-summary.md`) must never contain the full estimation table. `backlog-summary.md` may carry a lightweight `## Backlog Estimate` planning aid (Points + Key Driver only) — that is a batch-skill concern, not this component's output.
+
+## When to use
+
+Invoked as step 8c of `[[storywright-base]]` — **after step 9 (INVEST)** so the E verdict is available, **before step 10 (render)**. Never run before INVEST; the E verdict is a required input.
+
+## Inputs & interpretation
+
+- **story-context** — the completed canonical block (PM draft + dev draft) and the step-9 INVEST E verdict.
+- ACs and Business Rules are counted from `story.standard.md` (the PM draft).
+- Edge cases, dependencies, and high-severity risks are counted from `story.dev.md` (the dev draft).
+- The INVEST E verdict comes directly from step 9 output.
+
+## Application (step-by-step)
+
+### 1. Short-circuit: E = FAIL → Spike
+
+If step-9 INVEST yields `E — FAIL` (estimability failure), **do not run the formula**. Emit the Spike block and stop:
+
+```
+## Estimate
+
+**Story Points: Spike — estimate after spike completes**
+
+> ⚠️ This story has unresolved unknowns (INVEST E = FAIL). Run a technical spike first, then re-estimate once the unknowns are resolved.
+```
+
+### 2. Extract the six signals
+
+Read across both files:
+
+| Signal | Source file | Extraction rule |
+|--------|-------------|-----------------|
+| `ac_count` | `story.standard.md` | Count `**AC-\d+` pattern occurrences |
+| `rule_count` | `story.standard.md` | Count `^\d+\.` numbered rules; multi-variant rule (sub-bullets or `> ⚠️ Confirm:`) = 2 units; plain/inline-clause = 1 unit |
+| `edge_count` | `story.dev.md` | Count `^- \*\*` bullets under `^#{2,3} Edge Cases` section |
+| `dep_count` | `story.dev.md` | Count body rows under `^#{2,3} Dependencias` section |
+| `risk_hh_count` | `story.dev.md` | Count rows with 🚨 glyph under `^#{2,3} Riesgos` section (flagged high-severity only) |
+| `e_fail` | INVEST step-9 output | 1 if `E — FAIL`, else 0 (already handled in step 1) |
+
+**Section anchors are H2 by default** (`## Edge Cases`, `## Dependencias`, `## Riesgos`). Use the depth-agnostic pattern `^#{2,3}` as a fallback to tolerate H3 headings in non-standard goldens.
+
+**Source split is mandatory.** ACs and business rules live only in the PM draft, not the dev draft. Edge cases, deps, and risks live only in the dev draft. Counting from the wrong file produces zero for those signals.
+
+### 3. Compute raw score
+
+```
+raw = ac_count×1.0 + edge_count×0.6 + dep_count×1.5 + risk_hh_count×2.0 + rule_count×0.5
+```
+
+### 4. Map to Fibonacci bucket
+
+| Condition | Points |
+|-----------|--------|
+| raw ≤ 1.5 | 1 |
+| raw ≤ 3.5 | 2 |
+| raw ≤ 7.0 | 3 |
+| raw ≤ 12.5 | 5 |
+| raw ≤ 18.0 | 8 |
+| raw > 18.0 | 13 |
+
+### 5. Apply ±1 LLM adjustment (optional, bounded)
+
+You may adjust the deterministic bucket by exactly ±1 Fibonacci step **only if** you can cite one of the six named signals as the reason. A generic statement ("this feels complex") is not a valid citation.
+
+Format for the adjustment row:
+- With adjustment: `±1 → <new_points>: <signal_name> — <one-sentence reason>`
+- Without adjustment: `none — deterministic bucket retained`
+
+No citation means no adjustment. Use the bucket as-is.
+
+### 6. Split advisory for 13-point stories
+
+If the final point value is 13, append this advisory after the `## Estimate` section:
+
+```
+> ⚠️ Consider splitting: a 13-point story signals high complexity. Run `/storywright-story-split` to explore children — approval required before splitting.
+```
+
+This is advisory only. Never auto-split. Never change the point value.
+
+### 7. Emit ## Estimate in story.dev.md
+
+Place after the Definition of Done section, before the generation log.
+
+```markdown
+## Estimate
+
+**Story Points: N** (Fibonacci)
+
+| Signal | Value | Weight | Contribution |
+|--------|-------|--------|--------------|
+| Acceptance Criteria | <ac_count> | ×1.0 | <ac_count × 1.0> |
+| Edge Cases | <edge_count> | ×0.6 | <edge_count × 0.6> |
+| Dependencies | <dep_count> | ×1.5 | <dep_count × 1.5> |
+| High-severity Risks 🚨 | <risk_hh_count> | ×2.0 | <risk_hh_count × 2.0> |
+| Business Rules | <rule_count> | ×0.5 | <rule_count × 0.5> |
+| **Raw score** | | | **<raw>** → bucket <det_points> |
+| LLM adjustment | | | <adjustment row> |
+
+> Planning note: story points reflect relative complexity, not time, commitment, or velocity. Use them to compare stories against the calibration anchors below — not to forecast hours.
+```
+
+## Calibration anchors
+
+These real fixtures ground the scale. Use them to sanity-check your estimates before emitting:
+
+| Anchor | AC | Edge | Dep | 🚨 | Rules | Raw | Points | Notes |
+|--------|----|------|-----|----|-------|-----|--------|-------|
+| Synthetic simple | 1 | 0 | 0 | 0 | 0 | 1.0 | 1 | Single AC, no risk |
+| Synthetic small | 1 | 1 | 1 | 0 | 1 | 2.6 | 2 | Minimal enrichment |
+| Synthetic medium | 2 | 2 | 1 | 0 | 2 | 5.7 | 3 | Moderate AC/edge |
+| google-login | 1 | 5 | 3 | 1 | 3 | 12.0 | 5 | Auth flow, real golden |
+| backlog story-1 | 3 | 5 | 3 | 0 | 2 | 11.5 | 5 | Cart summary, real golden |
+| backlog story-2 (pre-adj) | 3 | 5 | 4 | 0 | 3 | 13.5 | 8 | Discount code, real golden |
+| Synthetic large | >9 | >5 | >5 | >1 | >3 | >18.0 | 13 | Split advisory fires |
+
+## Worked example: story-2 ±1 adjustment
+
+Story-2 (discount code) raw = 13.5 → deterministic bucket 8.
+
+LLM adjustment: −1 → 5. Citation: dependency "Resumen del carrito (Story 1 — AC-1)" — this is an intra-batch sibling already in-progress (Story 1), reducing uncertainty compared to a net-new external dep.
+
+Adjustment row: `−1 → 5: dep "Resumen del carrito (Story 1 — AC-1)" — intra-batch sibling already in-progress reduces implementation uncertainty`
+
+Final: **Story Points: 5**
+
+## Common Pitfalls
+
+- **Running step 8c before step 9 INVEST** — E verdict not yet available; do not skip INVEST ordering.
+- **Matching bare `###` headings in dev.md** — use the depth-agnostic `^#{2,3}` pattern; real goldens use `## H2` sections.
+- **Counting ACs or rules from dev.md** — they are PM-file signals only; dev.md has none.
+- **Counting edge/dep/risk from standard.md** — they are dev-file signals only; standard.md has none.
+- **Applying ±1 without a named signal citation** — if you cannot cite a specific signal, retain the deterministic bucket.
+- **Auto-splitting a 13-point story** — the advisory is informational; splitting requires user approval via `[[story-split]]`.
+- **Emitting ## Estimate in story.standard.md** — estimation lives in dev.md only; Rule H bans it from PM files.
+
+## References
+
+- [[storywright-base]]
+- [[invest-checklist]]
+- [[edge-cases]]
+- [[risks-and-dependencies]]
+- [[business-rules]]
+- [[acceptance-criteria]]
+
+<claude-specific>
+Respond in the user's detected language (auto-detected per storywright-base rule 4). The computation and table structure are language-neutral; translate labels (Signal, Value, Weight, Contribution, Planning note) to match.
+</claude-specific>

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

@@ -3,7 +3,7 @@ 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.5.0
+version: 2.6.0
 inputs:
   - none
 outputs:
@@ -100,10 +100,12 @@ If you are reading this through a top-level skill, treat every rule below as non
 
     **ALLOWED:** User Story, Acceptance Criteria, Definition of Done, Contexto, Business Goal, Scope, Out of Scope, Business Rules. (`**Summary:**` is inline text, not a section heading — it is not subject to this list.)
 
-    **BANNED** (move content to `story.dev.md`, never emit in PM files): Edge Cases, Non-Functional Requirements, NFR, Performance, Security, Accessibility, Technical Considerations, Analytics, Risks, Dependencies, Dependencias, Riesgos — and any section whose name does not appear in the ALLOWED list above.
+    **BANNED** (move content to `story.dev.md`, never emit in PM files): Edge Cases, Non-Functional Requirements, NFR, Performance, Security, Accessibility, Technical Considerations, Analytics, Risks, Dependencies, Dependencias, Riesgos, Estimate, Story Points — and any section whose name does not appear in the ALLOWED list above.
 
     If you find yourself writing a banned section into a PM file, stop. Move its content to `story.dev.md` instead (use `## Technical Considerations` as the target heading for Accessibility, Performance, and Security content). Do not silently drop it.
 
+14. **Project-less by design — never ground in the open repo.** storywright generates a forward contract for work that often does not exist yet; it is NOT a code-analysis tool. Do NOT read, scan, or infer from the files of any repository open in the session, even if they appear relevant. All technical detail in `story.dev.md` (endpoints, components, file paths, library choices) is **inferred from domain knowledge**, not read from a codebase. Mark any non-obvious technical inference with `⚠️ Assumed:` so the developer treats it as a starting point, not verified fact. Grounding silently against an open repo makes output non-deterministic (the same prompt yields different stories depending on what files happen to be open) and gives false confidence that inferred specifics were verified — neither is acceptable. If the user explicitly wants the story grounded in real code, that is out of scope: tell them to confirm the specifics against the codebase themselves.
+
 ### 4a. Language auto-detect — expanded signals (rule E)
 
 Run cheap detection before asking. Multi-signal weighted decision:
@@ -261,6 +263,16 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
    - `NEEDS REFINEMENT` → iterate failing dimension, max 1 cycle, then STOP.
    - `NOT A STORY` → tell user it's a tech task and stop.
 
+8c. **Estimate** via `[[estimation]]`. (Runs AFTER step 9 — requires the INVEST E verdict.)
+    1. Read the step-9 INVEST E verdict.
+    2. If `E — FAIL` → emit Spike block in `story.dev.md`; skip formula.
+    3. Else: read 6 signals across both drafts (`ac_count` + `rule_count` from `story.standard.md`; `edge_count` + `dep_count` + `risk_hh_count` from `story.dev.md`).
+    4. Run formula: `raw = AC×1.0 + edge×0.6 + dep×1.5 + 🚨×2.0 + rules×0.5`.
+    5. Map raw to Fibonacci bucket (≤1.5→1, ≤3.5→2, ≤7→3, ≤12.5→5, ≤18→8, >18→13).
+    6. Apply ±1 LLM adjustment only with a named signal citation; no citation → deterministic bucket retained.
+    7. Emit `## Estimate` section in `story.dev.md` only (after DoD, before generation log).
+    8. If points = 13 → append `> ⚠️ Consider splitting:` advisory (advisory only; never auto-split).
+
 10. **Render** via `[[story-formatter]]`.
     - Derive the output folder: `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` where `YYYY-MM-DD-HHmm` is the current local date+time and `<title-slug>` is the story title in kebab-case (max 5 words, drop articles/prepositions).
     - Use the `Write` tool to persist both files to that folder (create it if it does not exist):
@@ -287,6 +299,8 @@ Everything else is identical and lives in this base.
 
 ## Common Pitfalls (all skills)
 
+- Running step 8c (Estimate) before step 9 INVEST — E verdict not yet available; always run INVEST first.
+- Matching bare `###` headings in dev.md for estimation signal extraction — use depth-agnostic `^#{2,3}` pattern; rendered goldens use H2 sections.
 - Writing any sidecar question file (clarifications.md, questions.md, etc).
 - Announcing "Clarification resolved" or "no clarifications.md needed" instead of proceeding silently.
 - Offering to save a clarifications file to disk after resolving gaps.

package/skills/story-batch/SKILL.md

@@ -22,6 +22,7 @@ composes:
   - _components/definition-of-done
   - _components/invest-checklist
   - _components/story-formatter
+  - _components/estimation
 ---
 
 ## Purpose
@@ -159,6 +160,25 @@ Story pairs are already written by Phase 3 step 10. Emit:
 
    **GUARD — banned sections:** do not use headings that start with "Dependencies", "Dependencias", "Risks", or "Riesgos" — use "Dependency matrix" and "Notes" instead (base rule H).
 
+   After `## Stories` and before `## Dependency matrix`, include a `## Backlog Estimate` section as a planning aid:
+
+   ```
+   ## Backlog Estimate
+
+   | # | Title | Points | Key Driver |
+   |---|-------|--------|------------|
+   | 1 | ...   | 5      | 3 deps     |
+   | 2 | ...   | —  (split first) | SPLIT RECOMMENDED |
+   | 3 | ...   | Spike  | E = FAIL   |
+   |   | **Total drafted** | **10 SP** | sum of numeric values only |
+   ```
+
+   Rules:
+   - SPLIT RECOMMENDED items → `— (split first)` in Points column; `SPLIT RECOMMENDED` in Key Driver.
+   - Spike items (INVEST E = FAIL) → `Spike` in Points; `E = FAIL` in Key Driver.
+   - Total row sums only numeric point values; excludes `—` and `Spike` rows.
+   - Full justification table stays in `story-N.dev.md`; only Points + Key Driver appear here.
+
 2. **`.storywright-context.json`** updated per base rule 9 (one file per batch folder). No `clarifications.md`.
 
 3. **Flat folder structure:** all files in `docs/storywright/YYYY-MM-DD-HHmm-batch-<slug>/` with no subdirectories. Slug derived per Phase 0 rule (first item's feature area, ≤30 chars, lowercase, hyphens).

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

@@ -22,6 +22,7 @@ composes:
   - _components/definition-of-done
   - _components/invest-checklist
   - _components/story-formatter
+  - _components/estimation
 ---
 
 ## Purpose

package/skills/story-generate/SKILL.md

@@ -23,6 +23,7 @@ composes:
   - _components/definition-of-done
   - _components/invest-checklist
   - _components/story-formatter
+  - _components/estimation
 ---
 
 ## Purpose

package/skills/story-refine/SKILL.md

@@ -23,6 +23,7 @@ composes:
   - _components/definition-of-done
   - _components/invest-checklist
   - _components/story-formatter
+  - _components/estimation
 ---
 
 ## Purpose

package/skills/story-split/SKILL.md

@@ -26,6 +26,7 @@ composes:
   - _components/risks-and-dependencies
   - _components/definition-of-done
   - _components/story-formatter
+  - _components/estimation
 ---
 
 ## Purpose