write-shell-stories

Write Shell Stories

Generate or refresh the ## Shell Stories section of a Jira epic using comprehensive context from all linked sources (Figma, Confluence, Google Docs) and a scope analysis pass.

When to Use

Use when the user wants to:

• Generate the initial set of shell stories for an epic from its Figma designs and specs
• Refresh shell stories after new designs or scope changes
• Re-run to regenerate shell stories after questions have been answered (❓ → 💬 flipping in scope analysis)

Typical triggers:

• "Write shell stories for PROJ-123"
• "Generate shell stories for this epic"
• "Refresh the shell stories for PROJ-123 — we have new designs"

Required Input

• Jira epic key (e.g., PROJ-123) — the epic to write shell stories for

Procedure

Phase 1: Fetch the Epic

Call MCP tool extract-linked-resources with the Jira epic URL (e.g., https://myco.atlassian.net/browse/PROJ-123).

Save the returned markdown+frontmatter directly to .temp/cascade/context/jira-PROJ-123.md.

Parse discoveredLinks from frontmatter to build .temp/cascade/context/to-load.md.

Phase 2: Iterative Content Loading

For each non-Figma URL in to-load.md (prioritize parent and blocks relationships first):

1. Call extract-linked-resources with the URL
2. Save the returned markdown to .temp/cascade/context/{type}-{identifier}.md
3. Parse discoveredLinks from frontmatter — add any new URLs to to-load.md
4. Repeat until no unloaded non-Figma URLs remain

Important: Figma URLs are collected but NOT loaded here — they go in the ## Figma section of to-load.md for Phase 3.

Phase 3: Figma Batch Load

For each Figma URL collected:

1. Call MCP tool figma-batch-zip with the Figma file URL
   • This returns a downloadUrl and manifest
2. Try to download and extract:

   curl -sL "{downloadUrl}" -o /tmp/cascade-figma.zip && unzip -qo /tmp/cascade-figma.zip -d .temp/cascade/figma/ && rm /tmp/cascade-figma.zip
   

3. If curl succeeds, the extracted data is at:

   .temp/cascade/figma/{fileKey}/
   ├── manifest.json              ← frame list with metadata
   ├── prompts/
   │   └── frame-analysis.md      ← analysis prompt for frames
   └── frames/
       ├── {nodeId}-{name}/
       │   ├── image.png
       │   ├── structure.xml
       │   └── context.md
       └── ...
   

   → Proceed to Phase 4 (filesystem path).