story-mapping

Generate Jeff Patton user story maps as Markdown, Mermaid PDFs, drawio boards, and Lucidspark boards.

Updated Dec 1, 2025
One-click install
npx skills add https://github.com/jterratsdev/smart-deployment --skill story-mapping-jterratsdev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: story-mapping
Source: https://github.com/jterratsdev/smart-deployment/tree/main/.setup-agents/skills/story-mapping
Command: npx skills add https://github.com/jterratsdev/smart-deployment --skill story-mapping-jterratsdev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @mermaid-js/mermaid-cli, and includes scripts (resource) and assets (resource) components.

What problem does it solve? Turning a backlog of user stories into a coherent visual story map is slow and error-prone when done by hand. This Skill produces structured story maps in the Jeff Patton format — personas, epics, prioritized user stories with Gherkin acceptance criteria — and renders them as Markdown documents, Mermaid PDF diagrams, drawio boards, and Lucidspark boards. ## Core Features & Use Cases - Story map generation: Produces paired Markdown and JSON artifacts under docs/story-map/ with epics, personas, priorities, and Gherkin acceptance criteria, following a US-N01 numbering convention. - Two board formats: Format 1 zonal overview boards for discovery and executive framing, and Format 2 per-feature sizing breakdowns with T-shirt estimates ([XXS]–[XXL]) for refinement and sprint planning. - Technical story maps: Derives enabling technical stories (Apex, Mule, Flow, LWC, Config, Framework) under each functional story in a dual-layer layout, with color-coded stickies and fit-to-content banners. - Rendering and board sync: Renders Mermaid diagrams to PDF via mermaid-cli with truncation-safe CSS, renders drawio boards via sf setup-agents diagram render, and manages Lucidspark boards with create/update/reflow modes backed by an item-ID cache. - Use Case: A business analyst asks for a story map of a Salesforce field-service project; the Skill writes docs/story-map/field-service.md and .json, renders a PDF overview, and creates a Lucidspark board with personas, epics, and prioritized stories. ## Quick Start Ask the assistant to create a story map for your project with its epics and user stories, and it will generate the Markdown, JSON, and rendered board under docs/story-map/.

Frequently Asked Questions about story-mapping

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a user story map with epics and personas?

Describe your project's epics and user stories and request a story map. The Skill writes a Markdown document and a structured JSON file with epics and stories arrays under docs/story-map/, using the Jeff Patton format with personas, priorities, and Gherkin acceptance criteria.

How do I render a Mermaid diagram to PDF without truncation?

Save the diagram as a .mmd file and run the included render-pdf.sh script, which calls mermaid-cli via npx with a custom CSS file that removes max-width constraints. The script validates the output and reports parse errors if the diagram syntax is invalid.

What is the difference between Format 1 and Format 2 story map boards?

Format 1 is a zonal overview board for discovery and executive framing, while Format 2 is a per-feature breakdown where every story carries a T-shirt sizing tag. Format 2 requires sizing data and is chosen only for refinement, estimation, or sprint planning requests.

Can I update an existing Lucidspark story map board instead of recreating it?

Yes. The update mode diffs the Markdown source against the live board using a cached item-ID file, then applies only the additions, changes, and confirmed deletions. The reflow mode repositions items and resizes grouping banners without changing any content.

Why does my Lucidspark board title show corrupted characters?

The Lucid MCP server has a UTF-8 encoding issue that corrupts non-ASCII characters like em-dashes in document titles. Substitute em-dashes with hyphens and verify the title by fetching the document back after creation.

When should a story sized XXL be handled differently?

An XXL size is a split gate, not an estimate. Stories tagged [XXL] must be broken into smaller stories of XL or below before they can be estimated in person-days or enter a sprint.