# Story Mapping Adoption Review

Task: STORY-MAPPING-SKILL-ADOPTION
Date: 2026-05-16

## Current Assessment

Open Orchestra has partial story map support in `src/lucid-story-map.ts`:

- deterministic Lucidspark payload creation.
- stable IDs for capabilities, features, business stories, and technical stories.
- update/reflow diff support.
- grouping banner reflow tests in `test/lucid-story-map.test.js`.

The reviewed external baseline has a broader reusable Story Mapping skill:

- Jeff Patton-style markdown template.
- personas, epics, user stories, priorities, and Gherkin acceptance criteria.
- Mermaid story map generation rules.
- Mermaid PDF rendering script and truncation-safe CSS.
- Lucidspark board constants, color map, layout zones, cache contract, update mode,
  reflow mode, conflict handling, grouping banner resizing, and UTF-8 title safety.

Conclusion: Open Orchestra has the engine-level Lucidspark payload foundation, but
does not yet expose Story Mapping as a first-class skill/workflow capability.

## Reusable Patterns

Bring these patterns into Open Orchestra:

- `story-mapping` skill metadata and trigger routing for `story map`, `story mapping`,
  `epic breakdown`, `backlog visualization`, and `release planning map`.
- Markdown story map template with personas, priority legend, epics, user stories, and
  acceptance criteria.
- Mermaid story map output path for lightweight offline rendering and evidence.
- PDF/SVG render validation that checks for parser failures and suspiciously small output.
- Lucidspark cache contract for create/update/reflow operations.
- Conflict rules: preserve untracked board items, require confirmation before deletes,
  and preserve manual positions during update mode.
- UTF-8 title safety for Lucid MCP document titles.

## Existing Open Orchestra Strengths

Do not replace these existing Open Orchestra rules:

- `src/lucid-story-map.ts` already has a narrow typed payload model and tests.
- `skills/diagram-export/SKILL.md` already includes the newer high-fidelity diagram
  rules added during UML recreation: diagram contracts, post-render visual QA,
  connector endpoint checks, line crossing review, editable/rendered equivalence, and
  source-free validation.
- `rules/diagram-quality.mdc` already captures stricter draw.io/SVG fidelity rules
  than the external baseline.

## Suggested Adoption Scope

1. Add `skills/story-mapping/SKILL.md` and `manifest.json`.
2. Register `story-mapping` in `src/skills-catalog.ts` for product owner, product
   manager, analyst/business analyst, architect, and UX/UI designer roles.
3. Add markdown-to-story-map parsing or a documented source JSON contract that feeds
   `createLucidsparkStoryMap`.
4. Add local Mermaid `.mmd` generation for story maps so offline agents can produce
   evidence without Lucid.
5. Add render evidence helpers using the existing `orchestra diagrams lint` path where
   Mermaid is used.
6. Extend tests to cover markdown template generation, Mermaid source generation,
   Lucidspark cache behavior, update mode, delete confirmation, and reflow.

## Diagram Rules Comparison

External baseline diagram rules to consider:

- Salesforce Architect diagram type decision matrix.
- schema-first Lucid MCP payload workflow.
- one-call-per-diagram Lucid creation.
- post-write Lucid validation for duplicates, icon-text gaps, bounds, phantom text,
  and orphan items.
- multi-page diagram payload guidance.
- token-efficient visual editing guidance: push to visual tools and avoid chat-only
  pixel nudging where a visual tool is available.

Open Orchestra already has:

- diagram lint command and evidence recording.
- prompt registry coverage for `diagrams.md`.
- high-fidelity draw.io/SVG quality rules from the UML recreation iterations.
- source-free diagram contract requirement.

Recommendation: merge external baseline Lucid-specific operational checks and story-map
skill model into Open Orchestra, but keep Open Orchestra's stricter high-fidelity
diagram QA rules as the master visual quality layer.

## Open Questions

- Should Story Mapping be a CLI command (`orchestra story-map ...`) or remain a skill
  invoked by workflow roles?
- Should markdown be the source of truth, or should Open Orchestra use a typed JSON
  source file and generate markdown/Mermaid/Lucidspark from it?
- Should Lucid/Lucidspark cache files live in `docs/story-map/.cache/` or under
  `.agent-workflow/artifacts/story-map/`?