Story Map Skill
MartinForReal/storymap-skill
Mapeia histórias de usuário em planos de entrega priorizados e fatiaveis
Ver no GitHubSkill que transforma objetivos, briefings ou backlogs desorganizados em planos de entrega fatiados usando a metodologia de Jeff Patton. Gera mapa de histórias em múltiplos formatos, prioriza tarefas com WSJF/RICE/MoSCoW e valida dependências e cobertura de OKRs.
Instalação
npx convez-ai MartinForReal/storymap-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Estruturar backlogs caóticos em entregas incrementais
- Priorizar histórias usando WSJF, RICE ou MoSCoW
- Gerar critérios de aceitação e testes E2E para primeira fatia
- Alinhar histórias com OKRs e detectar lacunas
Veredito

Skill robusto e bem-testado (98.3% no benchmark) que resolve um problema real: transformar demandas nebulosas em roadmaps executáveis. Integração com Claude Code, MCP e frameworks irmãos (Superpowers, gstack, GSD) o torna prático para times que trabalham em ciclos curtos. Recomendado para PMs e tech leads que enfrentam backlogs desorganizados.
README
A tradução para o português deste README ainda está na fila.
storymap-skill
An Agent Skill that runs user story mapping (Jeff Patton style) to turn a goal, brief, or messy backlog into a sliced, prioritized delivery plan.
Built primarily for Claude Code, but works across any agent that supports the Agent Skills open standard — including Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, OpenCode, Goose, Letta, Roo, Kiro, and ~30 others.
It produces a project design doc, a three-format story map (markdown + Mermaid + CSV), a prioritized backlog (WSJF / RICE / MoSCoW), and optionally Given/When/Then acceptance criteria + an E2E test contract for slice 1.
Plays well inside Superpowers, gstack, and GSD. Works fine standalone.
What it does
- Four invocation modes — from scratch (verbal idea), from a brief/PRD, from an existing messy backlog, iterative refinement of a prior map
- Adaptive context loop — mines README, code, tests, ADRs, commit log, Jira/ADO/GitHub via MCP, sister-framework state (
.gsd/,.superpowers/), and priordesign.mdBEFORE asking the user - Customer-interview synthesis — extracts personas/activities/problems from raw transcripts with verbatim-quote preservation
- Persona simulation — spawns role-play subagents to fill gaps + surface stakeholder conflicts (user-input-authoritative — sim never overrides user)
- Six backbone-generation criteria — frame, persona perspective, time horizon, granularity, scope, aggregation (user-confirmed + recorded for reproducibility)
- Three slicing strategies — Patton classic, SAFe PI, Now/Next/Later
- Three prioritization methods — WSJF, RICE, MoSCoW
- Dependency tracking —
depends_oncolumn, cycle detection, slice-1 feasibility check - OKR alignment — coverage matrix, orphan stories + orphan KRs
- Acceptance criteria — Given/When/Then for slice 1 + INVEST check
- E2E test contract — backbone activities as E2E swimlanes
- Mode D limit-breach detection — capacity / dependencies / OKR coverage / scope; surfaces trade-offs rather than silently absorbing
- Output routing — from-scratch projects → seed an issue tracker (Jira/ADO/GitHub Projects/Linear/Trello); existing projects → keep-in-place cascade (sister-framework state →
TODO.md→ Memory MCP), with optional Claude CodeTodoWritepairing when the user is about to execute - Persistent memory — opt-in
.user-story-mapping/state.jsonor MCP memory server - Skill chaining — invokes other installed skills (code-explorer, db-analyzer, etc.) for context gathering
Installation
As a Claude Code plugin (recommended)
The repo is a self-contained Claude Code plugin marketplace. From inside Claude Code:
/plugin marketplace add martinforreal/storymap-skill
/plugin install storymap-skill@storymap-skill
That's it — Claude Code picks up the .claude-plugin/marketplace.json and installs the bundled skill (located at skills/user-story-mapping/).
As a raw Agent Skill (for any compatible host)
The packaged .skill artifact is built by CI on tag push and attached to each release — download user-story-mapping.skill from the assets and install it via your host's skill installer:
- Cursor / Codex CLI / Goose / Letta / Roo / Kiro / OpenCode / ~30 others — drop into the host's skills directory, or use the host's CLI installer
- Claude Code (manual install path) — copy
skills/user-story-mapping/into~/.claude/skills/
# Manual install from source
git clone https://github.com/martinforreal/storymap-skill.git
cp -r storymap-skill/skills/user-story-mapping ~/.claude/skills/
# Or build the .skill bundle yourself:
git clone https://github.com/martinforreal/storymap-skill.git
cd storymap-skill
python scripts/build_skill_bundle.py # writes user-story-mapping.skill
Verify
Once installed, the skill triggers on prompts like:
- "What should we build first for X?"
- "Help me find the MVP slice"
- "Organize this backlog"
- "PI planning"
- "Scope this project"
File structure
storymap-skill/ # repo root = Claude Code plugin
├── .claude-plugin/
│ ├── plugin.json # plugin manifest (Claude Code)
│ └── marketplace.json # self-marketplace entry
├── skills/
│ └── user-story-mapping/ # the skill itself (Agent Skills v1)
│ ├── SKILL.md # entry point — workflow at a glance + 6 steps
│ ├── assets/
│ │ ├── storymap-template.md # canonical markdown format the scripts parse
│ │ ├── design-doc-template.md # design doc with Backbone criteria + source tagging
│ │ ├── backlog-template.csv # backlog with WSJF/RICE/MoSCoW/depends_on/okr columns
│ │ └── backlog-summary-template.md
│ ├── evals/
│ │ └── evals.json # 18 consolidated test scenarios across 9 categories
│ ├── references/ # 14 reference files loaded on demand
│ │ ├── context-collection.md # Step 0 adaptive loop, framework artifacts, skill chaining
│ │ ├── customer-interview-synthesis.md # raw notes → personas/activities/hypotheses
│ │ ├── persistent-knowledge.md # memory across sessions
│ │ ├── persona-simulation-and-gap-filling.md # Step 0.4 — role-play subagents, conflict matrix
│ │ ├── discovery-questions.md # Mode A question bank
│ │ ├── slicing-strategies.md # Patton / SAFe PI / Now-Next-Later + cross-cutting rule
│ │ ├── prioritization-frameworks.md # WSJF / RICE / MoSCoW with worked examples
│ │ ├── dependency-tracking.md # depends_on column, cycle detection
│ │ ├── okr-alignment.md # OKR coverage matrix
│ │ ├── acceptance-criteria.md # Given/When/Then generation + INVEST
│ │ ├── e2e-verification-and-contract.md # backbone-as-E2E-contract
│ │ ├── iterative-refinement-and-snapshots.md # Mode D: snapshot + breach detection + diff
│ │ ├── framework-integration.md # Superpowers / gstack / GSD handoff patterns
│ │ └── work-item-tracking.md # Jira / ADO / GitHub / Linear / etc. import
│ └── scripts/
│ ├── storymap_to_csv.py # storymap.md → storymap.csv
│ └── storymap_to_mermaid.py # storymap.md → storymap.mmd
├── examples/ # sample outputs from 3 scenarios
├── tests/ # benchmark infrastructure
├── benchmark/ # latest published benchmark.json + benchmark.md
├── scripts/
│ └── build_skill_bundle.py # builds user-story-mapping.skill from skills/
├── .github/workflows/
│ └── release.yml # CI: builds .skill on tag push, attaches to release
├── CHANGELOG.md
├── LICENSE # MIT
└── README.md
Workflow at a glance
| Step | Purpose | Budget |
|---|---|---|
| 0 Context loop | Hypothesis-driven mining of cheap-then-conditional sources (works for both from-scratch and existing project) | <15% |
| 0.4 Fill gaps | List blocking gaps; ask user; if can't ask, spawn persona-sim subagents; gate planning on completeness | 15-20% |
| 1 Backbone | Left-to-right user activities; criteria user-confirmed + recorded | 5-10% |
| 2 Decompose | Tasks under activities; stories under tasks | 10-15% |
| 3 Slice | Walking-skeleton/PI/Now-Next-Later; first slice covers every backbone activity | 5% |
| 4 Prioritize | WSJF/RICE/MoSCoW + OKR linkage + dependency feasibility check | 15-20% |
| 4a ACs | Given/When/Then for slice-1 stories + INVEST check | 10-15% |
| 4b E2E contract | Backbone-as-contract: coverage matrix, E2E-HAPPY happy path, per-activity scenarios | 5-10% |
| 5 Generate derived | Run bundled scripts for storymap.csv + storymap.mmd | <2% |
| 6 Hand off | What was produced; what's still uncertain; smallest next decision | 5% |
Target total token budget: ~200K. Story count cap: ~50 total; slice-1 ≤ 15.
The user-input-authoritative principle
What the actual user told you, in this conversation, always wins. Lower-priority sources fill gaps but never override.
priority of sources (highest → lowest):
1. The actual user in this conversation
2. Verbatim from interview notes / call transcripts
3. Persistent memory from prior sessions (only if user approved)
4. Context mined from artifacts (README, code, tests, tracker)
5. Simulated persona responses
6. General-knowledge inference
Every fact in design.md is source-tagged so reviewers can audit later.
Examples
The examples/ directory contains sample outputs from three scenarios:
from-scratch-internal-tool/— Mode A, verbal-only fintech-refund-portal brief, WSJF, SAFe PImulti-stakeholder-conflict/— internal developer platform with conflicting stakeholders, user-input-authoritative principle in actionsnapshot-and-breaks-limits/— Mode D snapshot of a mid-flight PI, new feature requested, 6 limit breaches detected with trade-off options
Each contains the full 7-file output (design.md, storymap.md, storymap.csv, storymap.mmd, backlog.md, backlog.csv, handoff.md) plus slice-1-acceptance-criteria.md / breach-decisions.md where applicable.
Tests
evals/evals.json contains 18 consolidated test scenarios spanning:
- Invocation modes A/B/C/D
- App types: web, mobile (consumer + B2B), desktop, API/SDK, CLI, enterprise multi-tenant
- Framework integrations: Superpowers, gstack, GSD
- Capabilities: customer interview synthesis, dependency tracking, OKR alignment, persona simulation + conflict resolution, Mode D limit-breach detection, context loop short-circuit, framework-artifact mining + backbone criteria
Test infrastructure (grade_runs.py, build_benchmark.py, build_viewer.py, setup_iter10.py) lives in tests/. See tests/README.md.
Benchmark
Latest full benchmark (iteration 11, all 18 evals × {with-skill, baseline}):
| Configuration | Pass rate | Mean duration | Mean tokens |
|---|---|---|---|
| with-skill | 98.3% (171/174) | 554s | 215,947 |
| baseline (no skill) | 20.1% (35/174) | 236s | 162,905 |
| Δ | +78.2pp | +319s | +33% |
The skill adds ~33% tokens for a ~4.9× quality improvement. Per-eval breakdown + analyst notes in benchmark/benchmark.md; raw data in benchmark/benchmark.json. Regenerate locally with python tests/run-benchmark.sh or the individual scripts in tests/.
Where the skill earns its keep
- Structural conformance — all 6 canonical files in the canonical CSV/Mermaid format, every time. Baseline produces ad-hoc structures that don't import into Jira/ADO cleanly.
- Methodology correctness — WSJF/RICE/MoSCoW with all required columns, slice-1 backbone coverage rule honored, dependency cycles surfaced not silently broken.
- Capability-specific behaviors — persona conflict matrix with user-input-authoritative principle (eval-15), Mode D limit-breach detection with trade-off options (eval-16), framework-artifact mining without re-asking user (eval-18).
Where baseline closes the gap
- Eval-16 (Mode D + breach detection): 8/8 vs 6/8 — when the prompt explicitly demands breach surfacing, baseline does well. The skill's value is consistent breach detection across less-structured prompts.
- Evals 5, 15, 16: baseline 3-6 — when the user explicitly names the methodology in the prompt, baseline has something to grab onto.
When prompts are sparse, baseline collapses to 0-2/N.
Security considerations
Before installing any third-party Agent Skill (this one included):
- Audit the instructions. Read
SKILL.mdand thereferences/files. Skills are loaded into your agent's context and influence what it does. Treat the skill like a configuration file with side effects on agent behavior. - Audit the bundled scripts. This skill ships two Python files in
scripts/. Read them — they're <200 lines combined and only convert markdown to CSV / Mermaid. They do not access network, write outside the working directory, or read user secrets. - Check
compatibilityin SKILL.md frontmatter — this skill declares what it expects (Python 3.10+, no other system deps). - Don't put secrets in the skill's working directory. The skill mines context from files in the working directory. Keep
.env, credentials, etc. outside. - Tracker MCP access is opt-in. This skill can mine Jira / ADO / GitHub via MCP if the user wires those MCPs up — it never auto-installs them.
The skill never:
- Makes network calls (no
requests,urllib,httpximports) - Modifies code in the working directory (only writes to
<output-dir>/per the user's request) - Auto-invokes other skills (per spec — only the user does that)
- Persists state without explicit user opt-in (
.user-story-mapping/state.jsonis opt-in; seereferences/persistent-knowledge.md)
If you find a security concern, please open an issue.
License
MIT — see LICENSE.
Contributing
Issues and PRs welcome. When adding capabilities:
- Write the reference file first (
references/<your-feature>.md) - Update
SKILL.mdworkflow steps to call it out - Add at least one new test case to
evals/evals.json - Update assets (
backlog-template.csvetc.) if schema changes
Credits
Built iteratively with Claude Code's skill-creator plugin over 10 test iterations. Story mapping methodology per Jeff Patton's User Story Mapping (O'Reilly, 2014). Conforms to the Agent Skills v1 specification.
Changelog
See CHANGELOG.md.