Storymap

This skill runs a discovery-stage story mapping session — the point is shared understanding between whoever's building something and the people who'll use it, not a backlog. Never treat its output as decided behavior, and never produce code changes.

Rendering depends on the storymap CLI from MozaicWorks/storymap (MIT) — see the repo root README for install instructions. default.html.j2 (bundled here) is this skill's own template, not MozaicWorks' stock one; drop --template from the render commands below to get their original output instead.

Ground rules (Patton's method)

Infer, don't ask the user to write for you:

• Personas — who's affected, their role, tech comfort, goals and frustrations.
• User activities — the backbone: major things people do, in the order they naturally do them.
• User stories — concrete steps within each activity.
• MVP release and future releases — what's load-bearing now vs. genuinely later.

Organize entirely around user behavior. Never organize by technical architecture — no "API," "Database," "Frontend," "Backend" sections. Where real information is missing, write the assumption directly into the map rather than inventing a confident answer. Output only StoryMap markdown — no prose report wrapped around it, no code changes.

Before drafting anything

1. Read references/elicitation-questions.md (bundled with this skill). Pick 3-5 questions relevant to the feature area at hand and ask the user directly. If the AskUserQuestion tool isn't available in this session (observed in practice when running non-interactively, e.g. via claude -p) — ask the same questions as plain text in your reply and stop there, waiting for the user's actual answer before drafting. Do not skip straight to inferring a map either way; asking first is the point of this skill over a bare prompt.
2. Also pull a short list (5-8) of plain-language questions from the same reference that the user could take to actual stakeholders/end users. Present these separately, clearly labeled as "for real users," since Claude cannot answer them on stakeholders' behalf.
3. If this project has more than one product/codebase sharing the same domain (check for things like a strategy doc, multiple deploy targets, or the user mentioning "our other app"), ask which one this session is about, or whether it's deliberately comparing both — don't assume silently. If comparing two codebases and only one is actually checked out in the current workspace, mark anything about the other one as an explicit assumption inferred from docs/conversation, not a verified fact — don't imply you read code you didn't.
4. Default scope is one feature area per session. If the user explicitly asks for a whole-project or multi-feature pass instead, see "Whole-project backbone mode" below rather than drafting full detail everywhere.
5. Before drafting Personas/Releases, read storymap/_registry.md if it exists in this project. Reuse existing canonical names verbatim rather than re-typing a close-but-different name for the same persona/release — unreconciled renames are exactly how two sessions end up describing the same thing under different names with nothing tying them together. If a persona or feature doesn't exist yet, add it to the registry in this same session rather than improvising silently.

Whole-project backbone mode

Only when explicitly requested (e.g. "map the whole product," "just the backbone across everything"). This is the exception, not the default:

• Keep it deliberately shallow — one representative task and one representative story per activity, not full detail. The goal is a spine to point at, not a competing map.
• If prior per-feature story maps already exist for parts of this project, reuse their findings and persona names rather than re-deriving them from scratch, and reference those files by name.
• State plainly, inside the output, that this is a high-level pass and that going deeper on any single activity should become its own per-feature session producing its own file — don't let one file grow into the whole project's full detail.
• Keep persona/activity naming consistent with any existing per-feature maps in this project so files stay comparable/mergeable later.

Exact markdown syntax

The storymap CLI (storymap render <file>) parses a specific structure — this is not free-form markdown, and getting the heading levels wrong produces a file that "renders" with no warning but shows no content. Use exactly this shape (confirmed against storymap init's generated skeleton, not guessed from a screenshot or example image):

# <Product/Feature Title>          <- h1, one line of description below

# Releases                        <- h1, literally "Releases"
## <Release Name>                 <- h2 per release, description text below

# Personas                        <- h1, literally "Personas"
## <Persona Name>                 <- h2 per persona
- **Role:** ...
- **Tech level:** ...
(description paragraph)

# Map                             <- h1, literally "Map"
## <Activity>                     <- h2, a column group
### <Task>                        <- h3, a column within the activity
#### <Story text> [status:: X] [persona:: Y] [release:: Z]   <- h4, a card
(description paragraph)

Field rules:

• status must be exactly one of not-started | in-progress | done | blocked — no other values (not shipped, not unclear).
• release must exactly match a release name (or its id, see below) defined under # Releases, or the story won't appear in any swimlane.
• Any release name containing a space must carry an [id:: short-name] field on its ## <Release Name> heading (the CLI itself warns about this) — once assigned, story [release::] fields must reference the id, not the display text, so the heading can be renamed later without breaking references. Single-word names (Shipped, Next, Later) don't need one. If storymap/_registry.md exists in this project, check it for the full rule and a worked example.
• persona should match a name defined under # Personas.
• Activity (##) and Task (###) headings under # Map carry no body text of their own in the rendered output — put narrative content in the Story's description paragraph instead, not as loose text under an Activity/Task heading.
• feature, issue, and decision are optional bracket fields on story lines ([feature:: slug], [issue:: N], [decision:: N]) — the CLI silently ignores unrecognized keys, confirmed safe to add. Add feature only in whole-project-backbone-mode files or sessions spanning more than one feature; a single-feature session file doesn't need it (the file itself is already scoped to one feature — check storymap/_registry.md's Features section, if present, for existing slugs). Add issue/decision only on stories that resolve or depend on a tracked issue-tracker or decision-log entry.

Producing the map

• Write the map to storymap/<slug>-storymap.md in the current project (create the storymap/ directory if it doesn't exist), where <slug> is a short kebab-case name for the feature area.
• When writing each story's description, follow storymap_card_writing.md (bundled with this skill) — sentence length, paragraph structure, bullet usage, and its editorial checklist — before saving the card.
• Before finishing, render with this skill's template: storymap render storymap/<slug>-storymap.md --template ~/.claude/skills/storymap/default.html.j2. This both self-checks that the file parses and produces HTML with the click-to-toggle story descriptions this skill always uses (hidden by default, revealed by clicking a story's name) — no separate post-processing step is needed. A warning like "document appears empty — no releases or activities found" means the heading structure above wasn't followed — fix it and re-render. Don't hand back a file that hasn't been validated this way; a silently-empty render is the single most common failure mode of this skill.
• If storymap isn't installed or the render step errors for an unrelated reason, say so plainly rather than silently skipping validation.
• Some projects also serve story maps inside the app, from pre-built HTML fragments committed under storymap/fragments/. Those fragments come from the app's own fragment template, not this skill's default.html.j2, so the render above doesn't update them. If that directory exists, also run the project's fragment build (for example bin/rails story_maps:build) and commit the result alongside the Markdown. Never hand-edit a fragment.
• As part of that same self-check, if storymap/_registry.md exists, compare this file's Persona and Release h2 headings against its canonical names. Flag (don't block on) anything that doesn't match verbatim — it's a signal of drift worth a one-line note to the user, not a hard failure.

Closing every session

After the map, add a section titled # Candidate roadmap entries listing only the specific gaps, decisions, or open questions this session surfaced — not a restatement of the whole map. If this session follows up on an existing decision-log entry or issue-tracker item, name it explicitly in this section rather than leaving the connection implicit. The storymap CLI doesn't recognize this section and will emit a harmless "unrecognised section" warning for it when rendering — that's expected, it's for human review only. This is a suggestion list for the user to review and manually promote into wherever this project tracks decisions (a ROADMAP.md, issue tracker, spec-proposal step, etc.) — this skill never edits those artifacts itself, only suggests.