create-story-mode-guide

Imported from nicolasartman/reviewtato (skills/create-story-mode-guide/SKILL.md). Install upstream with npx skills add nicolasartman/reviewtato --skill create-story-mode-guide. Copyright stays with the author.

create-story-mode-guide — the story pass

You turn a PR into a short guided tour, writing story.json. The output shape is defined by example in ../create-pr-guide/reference/output-contract.md relative to this SKILL.md (normally ~/.claude/skills/create-pr-guide/reference/output-contract.md). Read its §5 before writing. If that file is missing, stop and tell the caller the create-pr-guide skill is not installed alongside this one — you cannot guarantee a valid file without the contract.

Inputs

Normally the orchestrator passes a guide directory and a context-pack path (with diff.patch, pr-meta.json, PR body, and grounding docs) plus config.

Standalone: if no context pack is passed, gather the minimum yourself with gh pr diff <ref> and gh pr view <ref> --json number,title,body,url,headRefName,baseRefName,headRefOid,files (or the branch-mode git commands from the orchestrator's SKILL.md §2). Resolve GUIDES_DIR and the guide key per the output contract; take pr.{owner,repo,number,headSha} from manifest.json verbatim. If no manifest.json exists yet, build one first per output-contract §3 with every required PrIdentity field populated — title, url, headBranch = headRefName, baseBranch = baseRefName, headSha = headRefOid, and host/owner/repo parsed from url — not a stripped-down stub, or the manifest itself fails the final validation.

Pick the genre from the diff + PR description

• User-facing change ⇒ user-flow story. Start where the user does — the UI entry point (the button, route, or command they hit) — and trace one key flow down through the layers. Each step is anchored to the code that handles that beat, in the order the user's action travels through the system.
• Infra / backend change ⇒ presentation story. Structure it like a short talk a human would give: grounding context first (what existed, what problem this solves), then each improvement in the order that builds understanding, until the whole unit of work is clear in both purpose and execution.

Read the PR title and body to decide; a diff that touches views/routes/UI leans user-facing, one that touches libraries/pipelines/config leans infra.

Authoring rules

• 5–15 steps, scaled by thoroughness (quick toward 5, thorough toward 15). Fewer strong steps beat many thin ones.
• Shape: one intro (kind intro, usually no anchor) → anchored steps in narrative order, NOT file order → one conclusion (kind conclusion, may omit the anchor). start points at the intro.
• Bodies answer why before what. 2–6 sentences. Name real symbols — actual function, file, and variable names from the diff — so a reader can map the prose to the code. Say why the change exists, then how it works.
• Anchors point only at lines actually visible in the diff — changed lines or their immediate context in a hunk. Never anchor to a line the reviewer cannot see on the "Files changed" page. Use side: "new" for head-side line numbers (added/context) and side: "old" for base-side (removed) lines.
• Branches are optional deep-dives. Offer a branch when a step invites a tangent — "Curious how cache invalidation works?" — pointing to an aside step. The aside covers the detour, then its next rejoins the main spine so the tour is never stranded. Keep the main line followable without taking any branch.

Graph integrity (the validator enforces this)

• Step ids unique; start names an existing step.
• Every next and every branches[].to names an existing step.
• Every non-start step is reachable from start by following next/branches — no orphans.
• At least one terminal step exists (no next, no branches) — normally the conclusion.
• Anchors well-formed: non-empty file, side ∈ {old,new}, 1 <= startLine <= endLine.

Trace the graph on paper before writing the file: follow start through every next and branch and confirm you reach every step and end somewhere.

Write, validate, iterate

Assemble story.json per the contract: a title, a summary (the elevator pitch, markdown), start, and steps. Copy pr.{owner,repo,number,headSha} from manifest.json. Then validate and fix until clean (≤ 3 attempts) per output-contract §6. The validator ships inside the create-pr-guide skill, installed side-by-side with this one:

node ~/.claude/skills/create-pr-guide/schema/validate.mjs "<guide-dir>"

If the skills live somewhere else, resolve ../create-pr-guide/schema/validate.mjs from this SKILL.md's directory to an absolute path yourself before invoking node — bash resolves relative paths against the current working directory, not this file.

Return a one-line summary (step and branch counts) to the caller.