@pavp/storywright 1.15.0 → 1.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +3 -2
- package/README.md +2 -2
- package/commands/story-batch.md +1 -1
- package/commands/story-from-figma.md +1 -1
- package/commands/story-generate.md +4 -5
- package/commands/story-refine.md +4 -5
- package/commands/story-split.md +1 -1
- package/package.json +1 -1
- package/skills/_components/acceptance-criteria/SKILL.md +1 -1
- package/skills/_components/business-rules/SKILL.md +1 -1
- package/skills/_components/definition-of-done/SKILL.md +2 -2
- package/skills/_components/edge-cases/SKILL.md +1 -1
- package/skills/_components/estimation/SKILL.md +165 -0
- package/skills/_components/{jira-wiki-formatter → story-formatter}/SKILL.md +21 -56
- package/skills/_components/storywright-base/SKILL.md +27 -16
- package/skills/story-batch/SKILL.md +31 -12
- package/skills/story-from-figma/SKILL.md +4 -4
- package/skills/story-generate/SKILL.md +4 -4
- package/skills/story-refine/SKILL.md +4 -4
- package/skills/story-split/SKILL.md +4 -5
- package/skills/story-generate/templates/story.jira-wiki.md +0 -40
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "storywright",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.17.0",
|
|
4
4
|
"description": "PM skills for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
|
|
5
5
|
"author": "pavp",
|
|
6
6
|
"license": "MIT",
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
"skills/_components/edge-cases",
|
|
22
22
|
"skills/_components/analytics-events",
|
|
23
23
|
"skills/_components/risks-and-dependencies",
|
|
24
|
-
"skills/_components/
|
|
24
|
+
"skills/_components/story-formatter",
|
|
25
|
+
"skills/_components/estimation"
|
|
25
26
|
],
|
|
26
27
|
"commands": [
|
|
27
28
|
"commands/story-generate.md",
|
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ this story is too big, split it:
|
|
|
57
57
|
<paste a story that visibly mixes flows>
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
Outputs always include
|
|
60
|
+
Outputs always include `story.standard.md` (PM-facing CommonMark) and `story.dev.md` (dev-facing CommonMark).
|
|
61
61
|
|
|
62
62
|
## Skills
|
|
63
63
|
|
|
@@ -78,7 +78,7 @@ Outputs always include both `story.jira-wiki.md` (Jira wiki markup) and `story.s
|
|
|
78
78
|
- `edge-cases` — boundary/network/concurrency/permission/state
|
|
79
79
|
- `analytics-events` — funnel events with payload taxonomy
|
|
80
80
|
- `risks-and-dependencies` — risks + blocking deps
|
|
81
|
-
- `
|
|
81
|
+
- `story-formatter` — portable Markdown renderer
|
|
82
82
|
|
|
83
83
|
## Multimodal
|
|
84
84
|
|
package/commands/story-batch.md
CHANGED
|
@@ -12,7 +12,7 @@ Follow the skill's procedure:
|
|
|
12
12
|
1. Phase 0 — parse the input structurally (numbered → bullets → blank-line blocks). Guard: if no items found, stop with guidance. If exactly 1 item, abort and redirect to `/storywright-story-generate`. Present parsed boundaries and wait for user confirmation.
|
|
13
13
|
2. Phase 1 — run the cohesion gate: extract persona and feature-area nouns per item, build the sharing graph, compute the largest-connected-component percentage. Announce verdict inline as `⚠️ Assumed:` blockquote. Honor PM overrides.
|
|
14
14
|
3. Phase 2 — cohesive batch: one shared clarification round (≤4 questions) over the union of items. Disparate batch: per-item clarifications deferred to base step 5.
|
|
15
|
-
4. Phase 3 — per-item pipeline: run base Application steps 3–11 for each confirmed item. Items with pre-split count ≥2 → SPLIT RECOMMENDED (no
|
|
15
|
+
4. Phase 3 — per-item pipeline: run base Application steps 3–11 for each confirmed item. Items with pre-split count ≥2 → SPLIT RECOMMENDED (no files, flag in summary, continue). Items with INVEST V = FAIL → NOT A STORY (no files, flag, continue). All other items emit both files `story-N.{standard,dev}.md`.
|
|
16
16
|
5. Phase 4 — cross-item analysis over DRAFTED items only: mechanical NxN dependency matrix, per-story V audit, topological build order.
|
|
17
17
|
6. Phase 5 — emit `backlog-summary.md` (cohesion verdict, INVEST table, dep matrix, V audit, build order, SPLIT RECOMMENDED notes) + `.storywright-context.json`. All files in flat folder `docs/storywright/YYYY-MM-DD-HHmm-batch-<slug>/`.
|
|
18
18
|
|
|
@@ -14,6 +14,6 @@ Follow the skill's procedure:
|
|
|
14
14
|
3. Phase 1 — inventory pages and frames; group by prototype links into flows.
|
|
15
15
|
4. Phase 2 — per flow: identify goal, entry point, states, components. Score per-inference confidence (HIGH/MEDIUM/LOW). Mark MEDIUM/LOW with `> ⚠️ Assumed:` blockquotes.
|
|
16
16
|
5. Phase 3 — for any flow that fails INVEST (Small) OR whose deterministic pre-split count ≥2, STOP that flow's draft, route to `/story-split`, and mark it `SPLIT RECOMMENDED` in `flow-summary.md`. Continue with the other flows.
|
|
17
|
-
6. Phase 4 — invoke `story-generate` per drafted flow. Emit
|
|
17
|
+
6. Phase 4 — invoke `story-generate` per drafted flow. Emit both files per story (`story-<N>.standard.md` + `story-<N>.dev.md`) + `flow-summary.md` mapping stories → frames for traceability.
|
|
18
18
|
|
|
19
19
|
Output in the input language (text language wins if mixed inputs).
|
|
@@ -15,12 +15,11 @@ Follow the skill's full procedure:
|
|
|
15
15
|
4. Fill the CORE sections (Title, Summary, User Story, Acceptance Criteria, Definition of Done).
|
|
16
16
|
5. Fill optional sections only if they have real content (drop empty ones).
|
|
17
17
|
6. Run INVEST pre-split test. If count ≥2, show candidate children + ask via `AskUserQuestion` with options: "Yes, split" / "Continue without split" / "No, keep as-is". Never auto-split silently. For other verdicts (NOT A STORY / NEEDS REFINEMENT / RUN A SPIKE) — STOP and hand off accordingly.
|
|
18
|
-
7. Render
|
|
19
|
-
- `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands
|
|
20
|
-
- `story.
|
|
21
|
-
- `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands)
|
|
18
|
+
7. Render two outputs via `story-formatter` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title kebab-case max 5 words). Use the `Write` tool for all files — never ask:
|
|
19
|
+
- `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands; DoD uses plain `- ` bullets (no checkboxes); no pipe tables
|
|
20
|
+
- `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands and `- [ ]` checkboxes)
|
|
22
21
|
- `.storywright-context.json` — resolved session answers: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`
|
|
23
|
-
Emit `story.standard.md`
|
|
22
|
+
Emit `story.standard.md` as a fenced code block in chat. Do NOT emit `story.dev.md` in chat.
|
|
24
23
|
8. Non-blocking assumptions remain? Mark inline with `⚠️ Assumed:`. Do NOT emit clarifications.md.
|
|
25
24
|
|
|
26
25
|
Output in the input language (preserve es/en).
|
package/commands/story-refine.md
CHANGED
|
@@ -16,10 +16,9 @@ Follow the skill's procedure:
|
|
|
16
16
|
4. Fill missing/weak sections via component skills. Preserve original wording where good.
|
|
17
17
|
5. Append a "Refinement log" at the end listing what changed.
|
|
18
18
|
6. Run INVEST pre-split test. If count ≥2, show candidate children + ask via `AskUserQuestion` with options: "Yes, split" / "Continue without split" / "No, keep as-is". Never auto-split silently.
|
|
19
|
-
7. Render
|
|
20
|
-
- `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands
|
|
21
|
-
- `story.
|
|
22
|
-
- `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands)
|
|
19
|
+
7. Render two outputs via `story-formatter` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title kebab-case max 5 words). Use the `Write` tool for all files — never ask:
|
|
20
|
+
- `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands; DoD uses plain `- ` bullets (no checkboxes); no pipe tables
|
|
21
|
+
- `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands and `- [ ]` checkboxes)
|
|
23
22
|
- `.storywright-context.json` — resolved session answers: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`
|
|
24
|
-
Emit `story.standard.md`
|
|
23
|
+
Emit `story.standard.md` as a fenced code block in chat. Do NOT emit `story.dev.md` in chat.
|
|
25
24
|
8. Non-blocking assumptions remain? Mark inline with `⚠️ Assumed:`. Do NOT emit clarifications.md.
|
package/commands/story-split.md
CHANGED
|
@@ -20,6 +20,6 @@ Follow the skill's procedure:
|
|
|
20
20
|
4. Draft a split plan as a Markdown table with rationale, pattern, and proposed children.
|
|
21
21
|
5. Run the strategic evaluation: does the split reveal low-value work? Are children equal-sized?
|
|
22
22
|
6. STOP and ask the user to approve / adjust / cancel. Never auto-split.
|
|
23
|
-
7. After approval: write `epic.md` (single file — epic metadata, holds the decision trail; NO `split-plan.md`) +
|
|
23
|
+
7. After approval: write `epic.md` (single file — epic metadata, holds the decision trail; NO `split-plan.md`) + both files per child (`story-<N>.standard.md` + `story-<N>.dev.md`).
|
|
24
24
|
8. Coherence check + recursive re-split for children still >1 sprint.
|
|
25
25
|
9. Save artifacts under the canonical output folder `docs/storywright/YYYY-MM-DD-HHmm-<epic-slug>/`.
|
package/package.json
CHANGED
|
@@ -39,7 +39,7 @@ Invoked by `story-generate` and `story-refine` after the body of the story is dr
|
|
|
39
39
|
- And <secondary observable outcome> (optional)
|
|
40
40
|
```
|
|
41
41
|
6. Number ACs `AC-1`, `AC-2`, …. This is the ONLY allowed scheme, in every language — never `CA-01`, `Criterio 1`, `Escenario 1`, or any localized variant. The `AC` label is fixed; translate only the scenario title after it. Stable numbering — never renumber when adding new ones in iterations.
|
|
42
|
-
7. Emit only the AC block. Do NOT include explanations, a section heading above the ACs, or surrounding prose. The host renderer (`[[
|
|
42
|
+
7. Emit only the AC block. Do NOT include explanations, a section heading above the ACs, or surrounding prose. The host renderer (`[[story-formatter]]`) owns the `## Acceptance Criteria` heading.
|
|
43
43
|
|
|
44
44
|
## Examples
|
|
45
45
|
|
|
@@ -17,7 +17,7 @@ Business rules are **policy invariants** the story must respect. They survive ac
|
|
|
17
17
|
|
|
18
18
|
## When to use
|
|
19
19
|
|
|
20
|
-
After the story body is drafted, before ACs are finalized — so ACs can reference relevant rules. Business Rules are an **optional PM section** (see `[[
|
|
20
|
+
After the story body is drafted, before ACs are finalized — so ACs can reference relevant rules. Business Rules are an **optional PM section** (see `[[story-formatter]]` — emit in `story.standard.md` only when non-empty) AND are also rendered in `story.dev.md`. They are policy invariants, not technical detail, so unlike edge-cases they are not dev-only.
|
|
21
21
|
|
|
22
22
|
## Inputs & interpretation
|
|
23
23
|
|
|
@@ -17,7 +17,7 @@ A Definition of Done is the contract for "shippable". It must be **checkable, ob
|
|
|
17
17
|
|
|
18
18
|
## When to use
|
|
19
19
|
|
|
20
|
-
Invoked after acceptance criteria and technical considerations are drafted. DoD is **dual-rendered** (see `[[
|
|
20
|
+
Invoked after acceptance criteria and technical considerations are drafted. DoD is **dual-rendered** (see `[[story-formatter]]`): `story.standard.md` carries the **acceptance-only** DoD projection (no CLI commands, no file-level criteria, plain `- ` bullets — no `- [ ]` checkboxes); `story.dev.md` carries the **full** DoD including CLI commands (`npm run test`), file-level lines, and `- [ ]` checkboxes. Produce both projections from the baseline below: PM projection = drop command/file lines AND strip `[ ]` to plain `- `; dev projection = keep everything including `- [ ]`.
|
|
21
21
|
|
|
22
22
|
## Inputs & interpretation
|
|
23
23
|
|
|
@@ -29,7 +29,7 @@ Invoked after acceptance criteria and technical considerations are drafted. DoD
|
|
|
29
29
|
1. Start from the baseline list below.
|
|
30
30
|
2. Drop lines that don't apply (e.g., no analytics if the story is purely internal).
|
|
31
31
|
3. Add story-specific lines from technical considerations (e.g., "Database migration runs cleanly on staging").
|
|
32
|
-
4. Use checkbox markdown (`- [ ]`) so reviewers can tick during review.
|
|
32
|
+
4. Use checkbox markdown (`- [ ]`) so reviewers can tick during review. **PM projection exception:** when rendering the DoD for `story.standard.md`, replace `- [ ]` with plain `- ` bullets — Jira Cloud does not autoformat task-list syntax. `story.dev.md` keeps `- [ ]` unchanged.
|
|
33
33
|
|
|
34
34
|
### Baseline DoD
|
|
35
35
|
|
|
@@ -16,7 +16,7 @@ Edge cases are how engineers find latent risk. Generate them **before** acceptan
|
|
|
16
16
|
|
|
17
17
|
## When to use
|
|
18
18
|
|
|
19
|
-
**Dev-file only.** Invoked while rendering `story.dev.md` (the dev-facing file), never the PM-facing `story.standard.md
|
|
19
|
+
**Dev-file only.** Invoked while rendering `story.dev.md` (the dev-facing file), never the PM-facing `story.standard.md`. `[[storywright-base]]` rule 3 forbids an Edge Cases section in the PM story body — this output lands exclusively in `story.dev.md`. It still informs AC failure paths (`[[acceptance-criteria]]`): the AC covers the observable behavior in the PM file; the enumerated technical edge detail lives in dev.md.
|
|
20
20
|
|
|
21
21
|
## Inputs & interpretation
|
|
22
22
|
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estimation
|
|
3
|
+
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.
|
|
4
|
+
trigger: "internal use by story-* skills"
|
|
5
|
+
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.
|
|
6
|
+
version: 1.0.0
|
|
7
|
+
inputs:
|
|
8
|
+
- story-context
|
|
9
|
+
outputs:
|
|
10
|
+
- estimate-block (dev.md only)
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Purpose
|
|
14
|
+
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
## When to use
|
|
20
|
+
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
## Inputs & interpretation
|
|
24
|
+
|
|
25
|
+
- **story-context** — the completed canonical block (PM draft + dev draft) and the step-9 INVEST E verdict.
|
|
26
|
+
- ACs and Business Rules are counted from `story.standard.md` (the PM draft).
|
|
27
|
+
- Edge cases, dependencies, and high-severity risks are counted from `story.dev.md` (the dev draft).
|
|
28
|
+
- The INVEST E verdict comes directly from step 9 output.
|
|
29
|
+
|
|
30
|
+
## Application (step-by-step)
|
|
31
|
+
|
|
32
|
+
### 1. Short-circuit: E = FAIL → Spike
|
|
33
|
+
|
|
34
|
+
If step-9 INVEST yields `E — FAIL` (estimability failure), **do not run the formula**. Emit the Spike block and stop:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
## Estimate
|
|
38
|
+
|
|
39
|
+
**Story Points: Spike — estimate after spike completes**
|
|
40
|
+
|
|
41
|
+
> ⚠️ This story has unresolved unknowns (INVEST E = FAIL). Run a technical spike first, then re-estimate once the unknowns are resolved.
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 2. Extract the six signals
|
|
45
|
+
|
|
46
|
+
Read across both files:
|
|
47
|
+
|
|
48
|
+
| Signal | Source file | Extraction rule |
|
|
49
|
+
|--------|-------------|-----------------|
|
|
50
|
+
| `ac_count` | `story.standard.md` | Count `**AC-\d+` pattern occurrences |
|
|
51
|
+
| `rule_count` | `story.standard.md` | Count `^\d+\.` numbered rules; multi-variant rule (sub-bullets or `> ⚠️ Confirm:`) = 2 units; plain/inline-clause = 1 unit |
|
|
52
|
+
| `edge_count` | `story.dev.md` | Count `^- \*\*` bullets under `^#{2,3} Edge Cases` section |
|
|
53
|
+
| `dep_count` | `story.dev.md` | Count body rows under `^#{2,3} Dependencias` section |
|
|
54
|
+
| `risk_hh_count` | `story.dev.md` | Count rows with 🚨 glyph under `^#{2,3} Riesgos` section (flagged high-severity only) |
|
|
55
|
+
| `e_fail` | INVEST step-9 output | 1 if `E — FAIL`, else 0 (already handled in step 1) |
|
|
56
|
+
|
|
57
|
+
**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.
|
|
58
|
+
|
|
59
|
+
**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.
|
|
60
|
+
|
|
61
|
+
### 3. Compute raw score
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
raw = ac_count×1.0 + edge_count×0.6 + dep_count×1.5 + risk_hh_count×2.0 + rule_count×0.5
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 4. Map to Fibonacci bucket
|
|
68
|
+
|
|
69
|
+
| Condition | Points |
|
|
70
|
+
|-----------|--------|
|
|
71
|
+
| raw ≤ 1.5 | 1 |
|
|
72
|
+
| raw ≤ 3.5 | 2 |
|
|
73
|
+
| raw ≤ 7.0 | 3 |
|
|
74
|
+
| raw ≤ 12.5 | 5 |
|
|
75
|
+
| raw ≤ 18.0 | 8 |
|
|
76
|
+
| raw > 18.0 | 13 |
|
|
77
|
+
|
|
78
|
+
### 5. Apply ±1 LLM adjustment (optional, bounded)
|
|
79
|
+
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
Format for the adjustment row:
|
|
83
|
+
- With adjustment: `±1 → <new_points>: <signal_name> — <one-sentence reason>`
|
|
84
|
+
- Without adjustment: `none — deterministic bucket retained`
|
|
85
|
+
|
|
86
|
+
No citation means no adjustment. Use the bucket as-is.
|
|
87
|
+
|
|
88
|
+
### 6. Split advisory for 13-point stories
|
|
89
|
+
|
|
90
|
+
If the final point value is 13, append this advisory after the `## Estimate` section:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
> ⚠️ Consider splitting: a 13-point story signals high complexity. Run `/storywright-story-split` to explore children — approval required before splitting.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
This is advisory only. Never auto-split. Never change the point value.
|
|
97
|
+
|
|
98
|
+
### 7. Emit ## Estimate in story.dev.md
|
|
99
|
+
|
|
100
|
+
Place after the Definition of Done section, before the generation log.
|
|
101
|
+
|
|
102
|
+
```markdown
|
|
103
|
+
## Estimate
|
|
104
|
+
|
|
105
|
+
**Story Points: N** (Fibonacci)
|
|
106
|
+
|
|
107
|
+
| Signal | Value | Weight | Contribution |
|
|
108
|
+
|--------|-------|--------|--------------|
|
|
109
|
+
| Acceptance Criteria | <ac_count> | ×1.0 | <ac_count × 1.0> |
|
|
110
|
+
| Edge Cases | <edge_count> | ×0.6 | <edge_count × 0.6> |
|
|
111
|
+
| Dependencies | <dep_count> | ×1.5 | <dep_count × 1.5> |
|
|
112
|
+
| High-severity Risks 🚨 | <risk_hh_count> | ×2.0 | <risk_hh_count × 2.0> |
|
|
113
|
+
| Business Rules | <rule_count> | ×0.5 | <rule_count × 0.5> |
|
|
114
|
+
| **Raw score** | | | **<raw>** → bucket <det_points> |
|
|
115
|
+
| LLM adjustment | | | <adjustment row> |
|
|
116
|
+
|
|
117
|
+
> 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.
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Calibration anchors
|
|
121
|
+
|
|
122
|
+
These real fixtures ground the scale. Use them to sanity-check your estimates before emitting:
|
|
123
|
+
|
|
124
|
+
| Anchor | AC | Edge | Dep | 🚨 | Rules | Raw | Points | Notes |
|
|
125
|
+
|--------|----|------|-----|----|-------|-----|--------|-------|
|
|
126
|
+
| Synthetic simple | 1 | 0 | 0 | 0 | 0 | 1.0 | 1 | Single AC, no risk |
|
|
127
|
+
| Synthetic small | 1 | 1 | 1 | 0 | 1 | 2.6 | 2 | Minimal enrichment |
|
|
128
|
+
| Synthetic medium | 2 | 2 | 1 | 0 | 2 | 5.7 | 3 | Moderate AC/edge |
|
|
129
|
+
| google-login | 1 | 5 | 3 | 1 | 3 | 12.0 | 5 | Auth flow, real golden |
|
|
130
|
+
| backlog story-1 | 3 | 5 | 3 | 0 | 2 | 11.5 | 5 | Cart summary, real golden |
|
|
131
|
+
| backlog story-2 (pre-adj) | 3 | 5 | 4 | 0 | 3 | 13.5 | 8 | Discount code, real golden |
|
|
132
|
+
| Synthetic large | >9 | >5 | >5 | >1 | >3 | >18.0 | 13 | Split advisory fires |
|
|
133
|
+
|
|
134
|
+
## Worked example: story-2 ±1 adjustment
|
|
135
|
+
|
|
136
|
+
Story-2 (discount code) raw = 13.5 → deterministic bucket 8.
|
|
137
|
+
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
Adjustment row: `−1 → 5: dep "Resumen del carrito (Story 1 — AC-1)" — intra-batch sibling already in-progress reduces implementation uncertainty`
|
|
141
|
+
|
|
142
|
+
Final: **Story Points: 5**
|
|
143
|
+
|
|
144
|
+
## Common Pitfalls
|
|
145
|
+
|
|
146
|
+
- **Running step 8c before step 9 INVEST** — E verdict not yet available; do not skip INVEST ordering.
|
|
147
|
+
- **Matching bare `###` headings in dev.md** — use the depth-agnostic `^#{2,3}` pattern; real goldens use `## H2` sections.
|
|
148
|
+
- **Counting ACs or rules from dev.md** — they are PM-file signals only; dev.md has none.
|
|
149
|
+
- **Counting edge/dep/risk from standard.md** — they are dev-file signals only; standard.md has none.
|
|
150
|
+
- **Applying ±1 without a named signal citation** — if you cannot cite a specific signal, retain the deterministic bucket.
|
|
151
|
+
- **Auto-splitting a 13-point story** — the advisory is informational; splitting requires user approval via `[[story-split]]`.
|
|
152
|
+
- **Emitting ## Estimate in story.standard.md** — estimation lives in dev.md only; Rule H bans it from PM files.
|
|
153
|
+
|
|
154
|
+
## References
|
|
155
|
+
|
|
156
|
+
- [[storywright-base]]
|
|
157
|
+
- [[invest-checklist]]
|
|
158
|
+
- [[edge-cases]]
|
|
159
|
+
- [[risks-and-dependencies]]
|
|
160
|
+
- [[business-rules]]
|
|
161
|
+
- [[acceptance-criteria]]
|
|
162
|
+
|
|
163
|
+
<claude-specific>
|
|
164
|
+
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.
|
|
165
|
+
</claude-specific>
|
|
@@ -1,20 +1,19 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
3
|
-
description: Render a story into
|
|
2
|
+
name: story-formatter
|
|
3
|
+
description: Render a story into two files: story.standard.md (PM-facing CommonMark, no technical detail) and story.dev.md (dev-facing CommonMark, full technical detail).
|
|
4
4
|
trigger: "internal use by story-* skills"
|
|
5
|
-
intent: Component skill that takes a structured story and produces
|
|
6
|
-
version:
|
|
5
|
+
intent: Component skill that takes a structured story and produces two output files following the templates in story-generate/templates.
|
|
6
|
+
version: 3.0.0
|
|
7
7
|
inputs:
|
|
8
8
|
- structured-story
|
|
9
9
|
outputs:
|
|
10
10
|
- story.standard.md
|
|
11
|
-
- story.jira-wiki.md
|
|
12
11
|
- story.dev.md
|
|
13
12
|
---
|
|
14
13
|
|
|
15
14
|
## Purpose
|
|
16
15
|
|
|
17
|
-
Stories need to live in Jira
|
|
16
|
+
Stories need to live in Jira Cloud, Notion, Linear, GitHub Issues, and any other Markdown surface. Generate a portable CommonMark PM file and a full developer-facing file from the same source.
|
|
18
17
|
|
|
19
18
|
## When to use
|
|
20
19
|
|
|
@@ -26,12 +25,11 @@ Final step in `story-generate` and `story-refine`. Always last.
|
|
|
26
25
|
|
|
27
26
|
## Application (step-by-step)
|
|
28
27
|
|
|
29
|
-
## Audience separation —
|
|
28
|
+
## Audience separation — TWO files
|
|
30
29
|
|
|
31
30
|
| File | Audience | Technical detail |
|
|
32
31
|
|---|---|---|
|
|
33
32
|
| `story.standard.md` | PM, stakeholders | ❌ None — no file paths, no imports, no component names, no `npm run X` in DoD |
|
|
34
|
-
| `story.jira-wiki.md` | PM → Jira paste | ❌ None — same content as standard, Jira markup |
|
|
35
33
|
| `story.dev.md` | Developer | ✅ Full — file paths, imports, Technical Considerations, technical edge cases, full DoD with commands |
|
|
36
34
|
|
|
37
35
|
**What is "technical":** file paths, import statements, component/hook names, API method names, CLI commands (`npm run test`), null/undefined checks, browser API constraints (HTTPS, permissions), specific library flags.
|
|
@@ -42,75 +40,43 @@ Final step in `story-generate` and `story-refine`. Always last.
|
|
|
42
40
|
|
|
43
41
|
**Pre-emit heading guard (apply before writing any section to any file):**
|
|
44
42
|
- `story.standard.md` and `story.dev.md`: title line must use `#`; every section heading must use `##`. If received content uses `###` or `####` for a section, demote it to `##` before emitting.
|
|
45
|
-
- `story.jira-wiki.md`: title line must use `h2.`; every section heading must use `h3.`. If `h1.` or `h2.` appears on any line after the first heading, correct it to `h3.` before emitting.
|
|
46
43
|
|
|
47
44
|
Apply silently — no log entry needed for heading-level corrections.
|
|
48
45
|
|
|
49
|
-
1. Render `story.
|
|
50
|
-
- Headings: `h1. `, `h2. `, `h3. `
|
|
51
|
-
- Bold: `*text*`
|
|
52
|
-
- Italic: `_text_`
|
|
53
|
-
- Code: `{{code}}` inline, `{code}…{code}` block
|
|
54
|
-
- Lists: `* item`, `# item` (numbered)
|
|
55
|
-
- Tables: `||header||header||` then `|cell|cell|`
|
|
56
|
-
- Panels for callouts: `{panel:title=⚠️ Assumed}…{panel}`
|
|
57
|
-
- Strip all technical detail (see audience table above)
|
|
58
|
-
2. Render `story.standard.md` (PM-facing) using CommonMark:
|
|
46
|
+
1. Render `story.standard.md` (PM-facing) using CommonMark:
|
|
59
47
|
- Headings: `##`, `###`
|
|
60
48
|
- Bold: `**text**`
|
|
61
49
|
- Italic: `*text*`
|
|
62
50
|
- Code: `` `inline` ``, ```` ``` ```` blocks
|
|
63
51
|
- Lists: `- item`, `1. item`
|
|
64
|
-
- Tables: standard pipe tables
|
|
65
52
|
- Callouts: `> ⚠️ **Assumed:** …`
|
|
66
53
|
- Strip all technical detail (see audience table above)
|
|
67
|
-
|
|
54
|
+
- **No pipe tables.** PM files MUST NOT contain pipe-table Markdown (`| col | col |` rows). Render any tabular content as lists instead — Jira Cloud does not autoformat Markdown tables on paste.
|
|
55
|
+
- **DoD projection:** when rendering the Definition of Done block in `story.standard.md`, strip `[ ]` from each item — emit `- ` plain bullets, not `- [ ]` checkboxes. Jira Cloud does not autoformat task-list syntax into interactive checkboxes; plain bullets paste cleanly. The dev file keeps `- [ ]` unchanged.
|
|
56
|
+
2. Render `story.dev.md` (dev-facing) using CommonMark:
|
|
68
57
|
- Same structure as `story.standard.md` PLUS:
|
|
69
58
|
- Technical Considerations section (file paths, imports, API calls)
|
|
70
59
|
- Edge Cases section (null checks, error states, browser constraints)
|
|
71
|
-
- DoD includes CLI commands and file-level criteria
|
|
60
|
+
- DoD includes CLI commands and file-level criteria; uses `- [ ]` checkboxes
|
|
72
61
|
- Refinement log includes technical changes
|
|
73
|
-
|
|
62
|
+
3. Section model for PM files = **core + optional (non-technical)**.
|
|
74
63
|
|
|
75
64
|
**Core (always emit, in this order):**
|
|
76
65
|
1. Title
|
|
77
66
|
2. User Story (As a / I want to / so that)
|
|
78
67
|
3. Acceptance Criteria (observable behavior only)
|
|
79
|
-
4. Definition of Done (acceptance
|
|
68
|
+
4. Definition of Done (acceptance-only projection, plain `- ` bullets — no commands, no `- [ ]`)
|
|
80
69
|
|
|
81
70
|
**Optional PM sections (emit only if non-empty):**
|
|
82
71
|
5. Business Goal
|
|
83
72
|
6. Scope / Out of Scope
|
|
84
73
|
7. Business Rules
|
|
85
74
|
|
|
86
|
-
|
|
87
|
-
|
|
75
|
+
4. **Drop any section with no real content.** An empty heading is noise.
|
|
76
|
+
5. Emit `story.standard.md` as a fenced code block in chat (PM-facing). Do NOT emit `story.dev.md` in chat — write to disk only. File persistence is handled by the calling skill via the `Write` tool.
|
|
88
77
|
|
|
89
78
|
## Examples
|
|
90
79
|
|
|
91
|
-
### Good — Jira wiki
|
|
92
|
-
|
|
93
|
-
```
|
|
94
|
-
h2. Login con Google
|
|
95
|
-
|
|
96
|
-
Permitir a usuarios autenticarse mediante OAuth con Google.
|
|
97
|
-
|
|
98
|
-
h3. User Story
|
|
99
|
-
*As a* visitante nuevo
|
|
100
|
-
*I want* iniciar sesión con mi cuenta de Google
|
|
101
|
-
*So that* puedo evitar crear una nueva contraseña.
|
|
102
|
-
|
|
103
|
-
h3. Criterios de Aceptación
|
|
104
|
-
*AC-1: Login exitoso*
|
|
105
|
-
* Given el usuario está en la pantalla de login
|
|
106
|
-
* When toca "Continuar con Google" y autoriza una cuenta válida
|
|
107
|
-
* Then es redirigido al dashboard en <3s
|
|
108
|
-
|
|
109
|
-
h3. Definition of Done
|
|
110
|
-
* (/) Code merged behind feature flag
|
|
111
|
-
* (/) ACs pass in QA
|
|
112
|
-
```
|
|
113
|
-
|
|
114
80
|
### Good — CommonMark
|
|
115
81
|
|
|
116
82
|
```
|
|
@@ -130,17 +96,16 @@ Permitir a usuarios autenticarse mediante OAuth con Google.
|
|
|
130
96
|
- Then es redirigido al dashboard en <3s
|
|
131
97
|
|
|
132
98
|
## Definition of Done
|
|
133
|
-
-
|
|
134
|
-
-
|
|
99
|
+
- Code merged behind feature flag
|
|
100
|
+
- ACs pass in QA
|
|
135
101
|
```
|
|
136
102
|
|
|
137
103
|
## Common Pitfalls
|
|
138
104
|
|
|
139
|
-
-
|
|
140
|
-
-
|
|
141
|
-
- Emoji in Jira: works in cloud, often mangled in older self-hosted. Keep emojis to non-critical decoration.
|
|
105
|
+
- Emitting `- [ ]` checkboxes in PM-file DoD — use plain `- ` bullets in `story.standard.md`; keep `- [ ]` only in `story.dev.md`.
|
|
106
|
+
- Including pipe tables in PM files — render tabular content as lists instead.
|
|
142
107
|
- Empty headings. Drop.
|
|
143
|
-
- Wrong heading levels: CommonMark output uses `#` (H1) for title, `##` (H2) for sections.
|
|
108
|
+
- Wrong heading levels: CommonMark output uses `#` (H1) for title, `##` (H2) for sections. The canonical block in `[[storywright-base]]` uses `###`/`####` as taxonomy shorthand only — do not copy those levels into the rendered artifact.
|
|
144
109
|
- 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.
|
|
145
110
|
|
|
146
111
|
## References
|
|
@@ -148,5 +113,5 @@ Permitir a usuarios autenticarse mediante OAuth con Google.
|
|
|
148
113
|
- [[story-generate]] (templates live under `story-generate/templates/`)
|
|
149
114
|
|
|
150
115
|
<claude-specific>
|
|
151
|
-
Cache
|
|
116
|
+
Cache the CommonMark syntax table — it's stable. Remember: PM file DoD uses plain `- ` bullets; dev file DoD uses `- [ ]` checkboxes. PM files must not contain pipe tables.
|
|
152
117
|
</claude-specific>
|
|
@@ -31,14 +31,14 @@ If you are reading this through a top-level skill, treat every rule below as non
|
|
|
31
31
|
- ONE AC Scenario (one Given chain + one `When` + one `Then`).
|
|
32
32
|
If the input naturally needs >1 `When`/`Then`, the skill MUST stop the single-story path and route to `[[story-split]]`.
|
|
33
33
|
|
|
34
|
-
3. **No mini-PRDs in the PM story body.** PROHIBITED in `story.standard.md
|
|
34
|
+
3. **No mini-PRDs in the PM story body.** PROHIBITED in `story.standard.md`:
|
|
35
35
|
- Non-Functional Requirements blocks (a11y/i18n/perf/tokens) — DoD only.
|
|
36
36
|
- Edge Cases enumerated as their own section — fold into AC failure paths.
|
|
37
37
|
- Dependencies as prose — Jira ticket links only.
|
|
38
38
|
- Per-claim visual specs (pixel measurements, hex inferences) inline — use single banner (rule 5).
|
|
39
39
|
- Logs >3 lines (>5 if SPLIT verdict).
|
|
40
40
|
|
|
41
|
-
3a. **Technical detail lives in `story.dev.md`.** The content rule 3 bans from the PM body is NOT discarded — it is rendered in the dev-facing file. Edge cases, analytics events, risks/dependencies, technical considerations, and the command-level DoD belong in `story.dev.md`, populated by the enrichment components (Application step 8b). The PM↔dev split is the home for this content; rule 3 governs the PM
|
|
41
|
+
3a. **Technical detail lives in `story.dev.md`.** The content rule 3 bans from the PM body is NOT discarded — it is rendered in the dev-facing file. Edge cases, analytics events, risks/dependencies, technical considerations, and the command-level DoD belong in `story.dev.md`, populated by the enrichment components (Application step 8b). The PM↔dev split is the home for this content; rule 3 governs the PM file, `story.dev.md` carries the technical detail. See `[[story-formatter]]` for the audience table.
|
|
42
42
|
|
|
43
43
|
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.
|
|
44
44
|
|
|
@@ -96,11 +96,11 @@ If you are reading this through a top-level skill, treat every rule below as non
|
|
|
96
96
|
|
|
97
97
|
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.
|
|
98
98
|
|
|
99
|
-
13. **PM section whitelist (rule H).** Only these section names may appear in `story.standard.md
|
|
99
|
+
13. **PM section whitelist (rule H).** Only these section names may appear in `story.standard.md`:
|
|
100
100
|
|
|
101
101
|
**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.)
|
|
102
102
|
|
|
103
|
-
**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.
|
|
103
|
+
**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.
|
|
104
104
|
|
|
105
105
|
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.
|
|
106
106
|
|
|
@@ -171,7 +171,7 @@ Mechanical counter. Apply the table — do NOT eyeball:
|
|
|
171
171
|
|
|
172
172
|
## Canonical output shape (this is the WHOLE story — no exceptions)
|
|
173
173
|
|
|
174
|
-
> **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)
|
|
174
|
+
> **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). INVEST is a **process step** — it informs the Verdict line in the log but is NOT emitted as a section in the output artifact.
|
|
175
175
|
|
|
176
176
|
```markdown
|
|
177
177
|
### [Title]
|
|
@@ -232,15 +232,15 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
|
|
|
232
232
|
- Count ≤1 → continue to step 8 (single-story path).
|
|
233
233
|
- Count ≥2 → execute the **host skill's split behavior** (see Source-specific differential in each top-level skill).
|
|
234
234
|
|
|
235
|
-
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 **in the PM story body** — rule 3 still holds for `story.standard.md
|
|
235
|
+
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 **in the PM story body** — rule 3 still holds for `story.standard.md`.
|
|
236
236
|
|
|
237
|
-
**Summary line (mandatory).** Generate `**Summary:**` immediately after the title — one sentence, value-focused, no heading. This line is MANDATORY in
|
|
237
|
+
**Summary line (mandatory).** Generate `**Summary:**` immediately after the title — one sentence, value-focused, no heading. This line is MANDATORY in both output files. Format: `**Summary:** <sentence>`. Never omit it.
|
|
238
238
|
|
|
239
239
|
The Summary MUST open with WHAT the deliverable is and WHICH problem it solves, in business language. The rule 3 / rule H ban on technical detail (file paths, imports, component/CLI names) does NOT exempt you from explaining the purpose — "no technical names" means no jargon, NOT "no explanation of what it does." Strip the jargon, keep the purpose.
|
|
240
240
|
|
|
241
241
|
**For enabling / infra / platform stories this is mandatory and load-bearing.** When the deliverable is plumbing (publishing packages, provisioning a registry, setting up a pipeline, wiring shared config), describing only the process (publish / setup / install) is INSUFFICIENT — a PM reading it must understand what each artifact is FOR and what breaks downstream without it. State the consumer value, not the mechanics. Example: "publish 2 shared packages to a private registry" → the Summary explains what each package does and what stops working if it is missing, never just the publish/install cycle.
|
|
242
242
|
|
|
243
|
-
8.5. **PM section self-audit (rule H).** Before calling [[
|
|
243
|
+
8.5. **PM section self-audit (rule H).** Before calling [[story-formatter]], enumerate every section drafted for the PM file. For each section name:
|
|
244
244
|
- In Rule H ALLOWED list → keep.
|
|
245
245
|
- In Rule H BANNED list → move its content to `story.dev.md`.
|
|
246
246
|
- Not in either list → treat as BANNED, move to `story.dev.md`.
|
|
@@ -252,8 +252,8 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
|
|
|
252
252
|
- `[[risks-and-dependencies]]` → `### Dependencias` + `### Riesgos`
|
|
253
253
|
- `[[analytics-events]]` → `### Analytics / Eventos`
|
|
254
254
|
- `[[definition-of-done]]` → full DoD with CLI commands (PM files get the acceptance-only projection)
|
|
255
|
-
- `[[business-rules]]` → policy invariants (also an *optional* PM section per `[[
|
|
256
|
-
None of these may appear in the PM story body except the optional Business Rules section (see Rule H for the full PM section whitelist). Skip any component whose output is empty (drop empty sections — rule 3
|
|
255
|
+
- `[[business-rules]]` → policy invariants (also an *optional* PM section per `[[story-formatter]]` when non-empty)
|
|
256
|
+
None of these may appear in the PM story body except the optional Business Rules section (see Rule H for the full PM section whitelist). Skip any component whose output is empty (drop empty sections — rule 3).
|
|
257
257
|
|
|
258
258
|
9. **Run INVEST** via `[[invest-checklist]]`.
|
|
259
259
|
- `READY` → render.
|
|
@@ -261,15 +261,24 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
|
|
|
261
261
|
- `NEEDS REFINEMENT` → iterate failing dimension, max 1 cycle, then STOP.
|
|
262
262
|
- `NOT A STORY` → tell user it's a tech task and stop.
|
|
263
263
|
|
|
264
|
-
|
|
264
|
+
8c. **Estimate** via `[[estimation]]`. (Runs AFTER step 9 — requires the INVEST E verdict.)
|
|
265
|
+
1. Read the step-9 INVEST E verdict.
|
|
266
|
+
2. If `E — FAIL` → emit Spike block in `story.dev.md`; skip formula.
|
|
267
|
+
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`).
|
|
268
|
+
4. Run formula: `raw = AC×1.0 + edge×0.6 + dep×1.5 + 🚨×2.0 + rules×0.5`.
|
|
269
|
+
5. Map raw to Fibonacci bucket (≤1.5→1, ≤3.5→2, ≤7→3, ≤12.5→5, ≤18→8, >18→13).
|
|
270
|
+
6. Apply ±1 LLM adjustment only with a named signal citation; no citation → deterministic bucket retained.
|
|
271
|
+
7. Emit `## Estimate` section in `story.dev.md` only (after DoD, before generation log).
|
|
272
|
+
8. If points = 13 → append `> ⚠️ Consider splitting:` advisory (advisory only; never auto-split).
|
|
273
|
+
|
|
274
|
+
10. **Render** via `[[story-formatter]]`.
|
|
265
275
|
- 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).
|
|
266
|
-
- Use the `Write` tool to persist
|
|
276
|
+
- Use the `Write` tool to persist both files to that folder (create it if it does not exist):
|
|
267
277
|
- `story.standard.md` — PM-facing CommonMark, no technical detail
|
|
268
|
-
- `story.jira-wiki.md` — PM-facing Jira wiki markup, no technical detail
|
|
269
278
|
- `story.dev.md` — dev-facing CommonMark, full technical detail (file paths, imports, technical edge cases, full DoD with commands)
|
|
270
|
-
- Emit `story.standard.md`
|
|
279
|
+
- Emit `story.standard.md` as a fenced code block in chat. Do NOT emit `story.dev.md` in chat.
|
|
271
280
|
- Write `.storywright-context.json` to the same folder.
|
|
272
|
-
- Never ask whether to save — always write
|
|
281
|
+
- Never ask whether to save — always write both story files and the context JSON.
|
|
273
282
|
|
|
274
283
|
11. **Log** ≤3 bullets (≤5 if SPLIT) appended at story end. Log type label is host-specific (Generation / Refinement / Split).
|
|
275
284
|
|
|
@@ -288,6 +297,8 @@ Everything else is identical and lives in this base.
|
|
|
288
297
|
|
|
289
298
|
## Common Pitfalls (all skills)
|
|
290
299
|
|
|
300
|
+
- Running step 8c (Estimate) before step 9 INVEST — E verdict not yet available; always run INVEST first.
|
|
301
|
+
- Matching bare `###` headings in dev.md for estimation signal extraction — use depth-agnostic `^#{2,3}` pattern; rendered goldens use H2 sections.
|
|
291
302
|
- Writing any sidecar question file (clarifications.md, questions.md, etc).
|
|
292
303
|
- Announcing "Clarification resolved" or "no clarifications.md needed" instead of proceeding silently.
|
|
293
304
|
- Offering to save a clarifications file to disk after resolving gaps.
|
|
@@ -307,7 +318,7 @@ Everything else is identical and lives in this base.
|
|
|
307
318
|
- [[invest-checklist]]
|
|
308
319
|
- [[acceptance-criteria]]
|
|
309
320
|
- [[clarification-questions]]
|
|
310
|
-
- [[
|
|
321
|
+
- [[story-formatter]]
|
|
311
322
|
- [[story-generate]]
|
|
312
323
|
- [[story-refine]]
|
|
313
324
|
- [[story-split]]
|
|
@@ -8,7 +8,6 @@ inputs:
|
|
|
8
8
|
- backlog-text
|
|
9
9
|
outputs:
|
|
10
10
|
- story-1.standard.md
|
|
11
|
-
- story-1.jira-wiki.md
|
|
12
11
|
- story-1.dev.md
|
|
13
12
|
- backlog-summary.md
|
|
14
13
|
- .storywright-context.json
|
|
@@ -22,12 +21,13 @@ composes:
|
|
|
22
21
|
- _components/risks-and-dependencies
|
|
23
22
|
- _components/definition-of-done
|
|
24
23
|
- _components/invest-checklist
|
|
25
|
-
- _components/
|
|
24
|
+
- _components/story-formatter
|
|
25
|
+
- _components/estimation
|
|
26
26
|
---
|
|
27
27
|
|
|
28
28
|
## Purpose
|
|
29
29
|
|
|
30
|
-
A backlog input usually contains N discrete items — different features, improvements, or requirements listed together. This skill maps that multi-item input into Cohn+Gherkin stories — **one story per item, processed in a single invocation**.
|
|
30
|
+
A backlog input usually contains N discrete items — different features, improvements, or requirements listed together. This skill maps that multi-item input into Cohn+Gherkin stories — **one story per item, processed in a single invocation**. Each story emits two files: `story-N.standard.md` (PM-facing) + `story-N.dev.md` (dev-facing).
|
|
31
31
|
|
|
32
32
|
**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.**
|
|
33
33
|
|
|
@@ -54,7 +54,7 @@ This skill produces **multiple stories in one invocation** (one per confirmed it
|
|
|
54
54
|
|
|
55
55
|
For any item whose deterministic pre-split count ≥2 → STOP that item's draft, mark it `SPLIT RECOMMENDED` in `backlog-summary.md`, and continue with the remaining items. NEVER auto-invoke `[[story-split]]`.
|
|
56
56
|
|
|
57
|
-
For any item whose INVEST V dimension FAILS → mark it `NOT A STORY` in `backlog-summary.md`, emit no
|
|
57
|
+
For any item whose INVEST V dimension FAILS → mark it `NOT A STORY` in `backlog-summary.md`, emit no files, and continue. NEVER stop the batch.
|
|
58
58
|
|
|
59
59
|
If N=1 after boundary confirmation → abort and instruct the user to use `/storywright-story-generate` instead.
|
|
60
60
|
|
|
@@ -106,11 +106,11 @@ If the PM replies with an override, honor it and re-announce the new mode before
|
|
|
106
106
|
|
|
107
107
|
For each confirmed item (1-based index N):
|
|
108
108
|
|
|
109
|
-
1. Run base Application steps 3–11 verbatim (persona, passive-goal check, gap-check, pre-split count, canonical block, rule H audit, dev enrichment, INVEST, render
|
|
109
|
+
1. Run base Application steps 3–11 verbatim (persona, passive-goal check, gap-check, pre-split count, canonical block, rule H audit, dev enrichment, INVEST, render duo, log).
|
|
110
110
|
2. Use filename prefix `story-<N>.` (all items share one flat batch folder).
|
|
111
|
-
3. **Pre-split ≥2:** mark item as `SPLIT RECOMMENDED`, skip drafting the canonical block, emit no
|
|
112
|
-
4. **INVEST V = FAIL:** mark item as `NOT A STORY`, emit no
|
|
113
|
-
5. **INVEST other failures (T, N, E, I, S):** flag inline with `⚠️` in `backlog-summary.md` but still emit
|
|
111
|
+
3. **Pre-split ≥2:** mark item as `SPLIT RECOMMENDED`, skip drafting the canonical block, emit no files. Continue to the next item.
|
|
112
|
+
4. **INVEST V = FAIL:** mark item as `NOT A STORY`, emit no files. Continue to the next item.
|
|
113
|
+
5. **INVEST other failures (T, N, E, I, S):** flag inline with `⚠️` in `backlog-summary.md` but still emit both files (base behavior).
|
|
114
114
|
|
|
115
115
|
Only items in `DRAFTED` status (step 10 logged) proceed to the Phase 4 matrix.
|
|
116
116
|
|
|
@@ -124,7 +124,7 @@ Scope: only items that reached `DRAFTED` in Phase 3 participate in the matrix an
|
|
|
124
124
|
|
|
125
125
|
### Phase 5 — Output
|
|
126
126
|
|
|
127
|
-
|
|
127
|
+
Story pairs are already written by Phase 3 step 10. Emit:
|
|
128
128
|
|
|
129
129
|
1. **`backlog-summary.md`** at the batch folder root when N>1 OR any item is SPLIT RECOMMENDED or NOT A STORY:
|
|
130
130
|
|
|
@@ -133,8 +133,8 @@ Trios are already written by Phase 3 step 10. Emit:
|
|
|
133
133
|
|
|
134
134
|
Generated: YYYY-MM-DD HH:mm
|
|
135
135
|
Items: N
|
|
136
|
-
Drafted: D (story
|
|
137
|
-
Split recommended: S (no
|
|
136
|
+
Drafted: D (story pairs emitted)
|
|
137
|
+
Split recommended: S (no story files — run /storywright-story-split per item)
|
|
138
138
|
|
|
139
139
|
**Cohesion:** COHESIVE | DISPARATE (<cohesion%>, threshold 60%, driver: persona/area/both)
|
|
140
140
|
|
|
@@ -160,6 +160,25 @@ Trios are already written by Phase 3 step 10. Emit:
|
|
|
160
160
|
|
|
161
161
|
**GUARD — banned sections:** do not use headings that start with "Dependencies", "Dependencias", "Risks", or "Riesgos" — use "Dependency matrix" and "Notes" instead (base rule H).
|
|
162
162
|
|
|
163
|
+
After `## Stories` and before `## Dependency matrix`, include a `## Backlog Estimate` section as a planning aid:
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
## Backlog Estimate
|
|
167
|
+
|
|
168
|
+
| # | Title | Points | Key Driver |
|
|
169
|
+
|---|-------|--------|------------|
|
|
170
|
+
| 1 | ... | 5 | 3 deps |
|
|
171
|
+
| 2 | ... | — (split first) | SPLIT RECOMMENDED |
|
|
172
|
+
| 3 | ... | Spike | E = FAIL |
|
|
173
|
+
| | **Total drafted** | **10 SP** | sum of numeric values only |
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Rules:
|
|
177
|
+
- SPLIT RECOMMENDED items → `— (split first)` in Points column; `SPLIT RECOMMENDED` in Key Driver.
|
|
178
|
+
- Spike items (INVEST E = FAIL) → `Spike` in Points; `E = FAIL` in Key Driver.
|
|
179
|
+
- Total row sums only numeric point values; excludes `—` and `Spike` rows.
|
|
180
|
+
- Full justification table stays in `story-N.dev.md`; only Points + Key Driver appear here.
|
|
181
|
+
|
|
163
182
|
2. **`.storywright-context.json`** updated per base rule 9 (one file per batch folder). No `clarifications.md`.
|
|
164
183
|
|
|
165
184
|
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).
|
|
@@ -172,7 +191,7 @@ NO `clarifications.md`. NO Edge Cases / NFR sections **in PM files** (they live
|
|
|
172
191
|
Input: numbered list of 3 checkout-related items.
|
|
173
192
|
- Phase 0 finds 3 items structurally.
|
|
174
193
|
- Phase 1: cohesion% = 100% → COHESIVE, one shared clarification round.
|
|
175
|
-
- Phase 3: items 1 and 2 pass INVEST →
|
|
194
|
+
- Phase 3: items 1 and 2 pass INVEST → story pairs emitted; item 3 has pre-split ≥2 → SPLIT RECOMMENDED, no files.
|
|
176
195
|
- Phase 5: `backlog-summary.md` with 3-row table (2 DRAFTED, 1 SPLIT RECOMMENDED), 2×2 dep matrix over items 1–2.
|
|
177
196
|
|
|
178
197
|
### Good — disparate batch
|
|
@@ -8,7 +8,6 @@ inputs:
|
|
|
8
8
|
- figma-link
|
|
9
9
|
outputs:
|
|
10
10
|
- story-1.standard.md
|
|
11
|
-
- story-1.jira-wiki.md
|
|
12
11
|
- story-1.dev.md
|
|
13
12
|
- flow-summary.md
|
|
14
13
|
- .storywright-context.json
|
|
@@ -22,7 +21,8 @@ composes:
|
|
|
22
21
|
- _components/risks-and-dependencies
|
|
23
22
|
- _components/definition-of-done
|
|
24
23
|
- _components/invest-checklist
|
|
25
|
-
- _components/
|
|
24
|
+
- _components/story-formatter
|
|
25
|
+
- _components/estimation
|
|
26
26
|
---
|
|
27
27
|
|
|
28
28
|
## Purpose
|
|
@@ -91,8 +91,8 @@ Use the base canonical output shape. Design Reference banner per source-specific
|
|
|
91
91
|
|
|
92
92
|
### Phase 5 — Output
|
|
93
93
|
|
|
94
|
-
Per drafted flow, render
|
|
95
|
-
- `story-<N>.standard.md`
|
|
94
|
+
Per drafted flow, render both files via `[[story-formatter]]` (same 2-file contract as `story-generate` / `story-refine`):
|
|
95
|
+
- `story-<N>.standard.md` (PM-facing) + `story-<N>.dev.md` (dev-facing).
|
|
96
96
|
|
|
97
97
|
If N>1 OR any flow was routed to split:
|
|
98
98
|
- `flow-summary.md` with the matrix, V audit, build order, and SPLIT-RECOMMENDED markers.
|
|
@@ -10,7 +10,6 @@ inputs:
|
|
|
10
10
|
- figma-link
|
|
11
11
|
outputs:
|
|
12
12
|
- story.standard.md
|
|
13
|
-
- story.jira-wiki.md
|
|
14
13
|
- story.dev.md
|
|
15
14
|
- .storywright-context.json
|
|
16
15
|
composes:
|
|
@@ -23,12 +22,13 @@ composes:
|
|
|
23
22
|
- _components/risks-and-dependencies
|
|
24
23
|
- _components/definition-of-done
|
|
25
24
|
- _components/invest-checklist
|
|
26
|
-
- _components/
|
|
25
|
+
- _components/story-formatter
|
|
26
|
+
- _components/estimation
|
|
27
27
|
---
|
|
28
28
|
|
|
29
29
|
## Purpose
|
|
30
30
|
|
|
31
|
-
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.
|
|
31
|
+
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. Emits two files: `story.standard.md` (PM-facing) + `story.dev.md` (dev-facing).
|
|
32
32
|
|
|
33
33
|
**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.**
|
|
34
34
|
|
|
@@ -56,7 +56,7 @@ If the base **deterministic pre-split test** returns count ≥2:
|
|
|
56
56
|
- Show candidate children + dep notes + V audit.
|
|
57
57
|
- Ask via `AskUserQuestion`: "This story has [N] independent flows. Run split now?" with options:
|
|
58
58
|
- "Yes, split" → execute `[[story-split]]` inline (epic + children + .storywright-context.json).
|
|
59
|
-
- "Continue without split" → proceed with single-story path (fill canonical block → INVEST → render
|
|
59
|
+
- "Continue without split" → proceed with single-story path (fill canonical block → INVEST → render both files).
|
|
60
60
|
- "No, keep as-is" → stop. No output written.
|
|
61
61
|
- Do NOT silently auto-split without the AskUserQuestion confirmation.
|
|
62
62
|
|
|
@@ -10,7 +10,6 @@ inputs:
|
|
|
10
10
|
- figma-link
|
|
11
11
|
outputs:
|
|
12
12
|
- story.standard.md
|
|
13
|
-
- story.jira-wiki.md
|
|
14
13
|
- story.dev.md
|
|
15
14
|
- .storywright-context.json
|
|
16
15
|
composes:
|
|
@@ -23,12 +22,13 @@ composes:
|
|
|
23
22
|
- _components/risks-and-dependencies
|
|
24
23
|
- _components/definition-of-done
|
|
25
24
|
- _components/invest-checklist
|
|
26
|
-
- _components/
|
|
25
|
+
- _components/story-formatter
|
|
26
|
+
- _components/estimation
|
|
27
27
|
---
|
|
28
28
|
|
|
29
29
|
## Purpose
|
|
30
30
|
|
|
31
|
-
Bring an existing user story up to standard *without* turning it into a feature spec.
|
|
31
|
+
Bring an existing user story up to standard *without* turning it into a feature spec. Emits two files: `story.standard.md` (PM-facing) + `story.dev.md` (dev-facing).
|
|
32
32
|
|
|
33
33
|
**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.**
|
|
34
34
|
|
|
@@ -48,7 +48,7 @@ If the base **deterministic pre-split test** returns count ≥2:
|
|
|
48
48
|
- Show candidate children + per-pair dep notes (base rule 10) + V audit (base rule 11).
|
|
49
49
|
- Ask via `AskUserQuestion`: "This story has [N] independent flows. Run split now?" with options:
|
|
50
50
|
- "Yes, split" → execute `[[story-split]]` inline (epic + children + .storywright-context.json).
|
|
51
|
-
- "Continue without split" → proceed with single-story path (fill canonical block → INVEST → render
|
|
51
|
+
- "Continue without split" → proceed with single-story path (fill canonical block → INVEST → render both files).
|
|
52
52
|
- "No, keep as-is" → stop. No output written.
|
|
53
53
|
- Do NOT silently auto-split without the AskUserQuestion confirmation.
|
|
54
54
|
|
|
@@ -11,10 +11,8 @@ inputs:
|
|
|
11
11
|
outputs:
|
|
12
12
|
- epic.md
|
|
13
13
|
- story-1.standard.md
|
|
14
|
-
- story-1.jira-wiki.md
|
|
15
14
|
- story-1.dev.md
|
|
16
15
|
- story-2.standard.md
|
|
17
|
-
- story-2.jira-wiki.md
|
|
18
16
|
- story-2.dev.md
|
|
19
17
|
- .storywright-context.json
|
|
20
18
|
composes:
|
|
@@ -27,7 +25,8 @@ composes:
|
|
|
27
25
|
- _components/analytics-events
|
|
28
26
|
- _components/risks-and-dependencies
|
|
29
27
|
- _components/definition-of-done
|
|
30
|
-
- _components/
|
|
28
|
+
- _components/story-formatter
|
|
29
|
+
- _components/estimation
|
|
31
30
|
---
|
|
32
31
|
|
|
33
32
|
## Purpose
|
|
@@ -45,7 +44,7 @@ When a story is an epic in disguise, splitting badly is worse than not splitting
|
|
|
45
44
|
|
|
46
45
|
This skill IS the split behavior. It always emits multiple files:
|
|
47
46
|
- `epic.md` — title, why-split, INVEST failure reasons, mechanical NxN matrix, build order, V audit per child, list of children. Single file (epic metadata, not a user story).
|
|
48
|
-
- Per child:
|
|
47
|
+
- Per child: both files `story-<N>.standard.md` + `story-<N>.dev.md`, rendered via `[[story-formatter]]` — same contract as every other story-producing skill. Each child is a canonical user story (per base shape).
|
|
49
48
|
- `.storywright-context.json` — persisted answers.
|
|
50
49
|
|
|
51
50
|
NO `split-plan.md`. The plan lives inside `epic.md`.
|
|
@@ -116,7 +115,7 @@ Follow the **base Application** skeleton for the front-end behaviors (context lo
|
|
|
116
115
|
|
|
117
116
|
5. **STOP and ask the user to approve via `AskUserQuestion`.**
|
|
118
117
|
|
|
119
|
-
6. **For each approved child, write the base canonical block, then render via `[[
|
|
118
|
+
6. **For each approved child, write the base canonical block, then render via `[[story-formatter]]` to both files** (`story-<N>.standard.md` + `story-<N>.dev.md`). The child's enrichment (edge cases, risks, analytics) populates its `story-<N>.dev.md` per base step 8b.
|
|
120
119
|
|
|
121
120
|
7. **Build dependency matrix mechanically (base rule 10).** Render in `epic.md`.
|
|
122
121
|
|
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
h2. {{Title}}
|
|
2
|
-
|
|
3
|
-
*Summary:* {{value-focused one-liner}}
|
|
4
|
-
|
|
5
|
-
h3. User Story
|
|
6
|
-
* *As a* {{persona}}
|
|
7
|
-
* *I want to* {{action}}
|
|
8
|
-
* *so that* {{outcome}}
|
|
9
|
-
|
|
10
|
-
h3. Acceptance Criteria
|
|
11
|
-
|
|
12
|
-
*AC-1: {{scenario title}}*
|
|
13
|
-
* *Given* {{precondition}}
|
|
14
|
-
* *When* {{trigger}}
|
|
15
|
-
* *Then* {{observable outcome}}
|
|
16
|
-
|
|
17
|
-
h3. Definition of Done
|
|
18
|
-
* (/) {{line 1}}
|
|
19
|
-
* (/) {{line 2}}
|
|
20
|
-
|
|
21
|
-
----
|
|
22
|
-
|
|
23
|
-
{panel:title=PM-facing — no technical detail}
|
|
24
|
-
Technical Considerations, Edge Cases, Analytics, Risks & Dependencies live in story.dev.md (rule 3). Optional sections below — keep only those with content.
|
|
25
|
-
{panel}
|
|
26
|
-
|
|
27
|
-
h3. Contexto
|
|
28
|
-
{{trigger: feedback / OKR / incident / competitor}}
|
|
29
|
-
|
|
30
|
-
h3. Business Goal
|
|
31
|
-
{{metric or hypothesis this moves}}
|
|
32
|
-
|
|
33
|
-
h3. Scope
|
|
34
|
-
* {{in 1}}
|
|
35
|
-
|
|
36
|
-
h3. Out of Scope
|
|
37
|
-
* {{out 1}}
|
|
38
|
-
|
|
39
|
-
h3. Business Rules
|
|
40
|
-
# {{rule 1}}
|