stage-chapters

What this skill does

# stage-chapters

Generates a Stage chapter run for the current local git branch and opens it in a browser. Uses `stagereview prep` to compute the diff, then generates chapters and a prologue, and hands the result to `stagereview show` to launch the SPA.

## Prerequisites

Run these checks before any other work. If either fails, stop with the error message — do not continue.

1. **`stagereview` is installed.** Run `which stagereview`. If it exits non-zero, instruct the user:

   ```
   stagereview is not installed. Run:

       npm install -g stagereview

   Then retry /stage-chapters.
   ```

   Stop.

2. **The current directory is a git repo.** Run `git rev-parse --is-inside-work-tree`. If it does not print `true`, stop with:

   ```
   /stage-chapters must be run inside a git repository.
   ```

## Step 1 — Run prep

```bash
PREP_FILE=$(stagereview prep)
```

`stagereview prep` auto-detects the base ref (main/master), computes the merge-base, generates the diff, filters out lockfiles/binaries, and formats hunks with line numbers for analysis. By default it auto-detects the diff scope: if uncommitted changes are present the diff includes staged, unstaged, and untracked files; otherwise it uses the committed branch diff. It writes a plain-text file and prints only the file path to stdout.

`prep` and `show` also accept positional git refs:

```bash
PREP_FILE=$(stagereview prep main)
PREP_FILE=$(stagereview prep main feature)
PREP_FILE=$(stagereview prep main..feature)
PREP_FILE=$(stagereview prep main...feature)
```

Use the same positional refs for `show`:

```bash
stagereview show "$AGENT_OUTPUT" main..feature
```

Both `prep` and `show` accept these optional flags:

- **`--base <ref>`** — base ref to diff against (default: auto-detect main/master).
- **`--compare <ref>`** — compare ref to diff against `--base`.
- **`--ref <mode>`** — diff scope. One of:
  - `work` — staged + unstaged + untracked changes (full working tree vs merge-base).
  - `staged` — only staged changes (index vs HEAD).
  - `unstaged` — only unstaged changes (working tree vs index).
  - Omitted — auto-detect (equivalent to `work` when uncommitted changes exist, committed branch diff otherwise).
- **`--pr <number-or-url>`** — review a GitHub pull request instead of the local branch. The base/head come from the PR itself, and its commits are fetched locally. Cannot be combined with positional refs, `--base`, `--compare`, or `--ref`. Requires `gh` to be installed and authenticated, and a github.com `origin` remote. Useful for reviewing a teammate's PR you don't have checked out.

When flags or positional refs are specified, pass the same scope to **both** `prep` and `show`:

```bash
PREP_FILE=$(stagereview prep --base feature-a --ref staged)
# ... later ...
stagereview show --base feature-a --ref staged "$AGENT_OUTPUT"

PREP_FILE=$(stagereview prep --base main --compare feature)
# ... later ...
stagereview show --base main --compare feature "$AGENT_OUTPUT"

# Review a GitHub PR by number or URL
PREP_FILE=$(stagereview prep --pr 123)
# ... later ...
stagereview show --pr 123 "$AGENT_OUTPUT"
```

If `prep` exits non-zero, relay its stderr to the user and stop.

**Do not modify files in the working tree between running `prep` and running `show`.** Both commands independently snapshot the git state. If the diff changes between them, `show` will reject the chapters with a hunk coverage error because the hunks no longer match.

## Step 2 — Read prep output

Read `$PREP_FILE` via the Read tool (or equivalent). For large diffs, use the Read tool's `offset` and `limit` parameters to read in chunks.

The file has two sections separated by headers:

1. **`=== COMMIT MESSAGES ===`** — `git log --oneline` output for prologue context.
2. **`=== HUNKS ===`** — formatted diff hunks with line numbers. Each hunk looks like:

```
=== File: src/app.ts (modified) | filePath: "src/app.ts", oldStart: 1 ===
=== Hunk @1: @@ -1,5 +1,6 @@ ===
1 1 | const a = 1;
2   |-const b = 2;
  2 |+const b = 3;
  3 |+const c = 4;
3 4 | const d = 5;
```

The two number columns are the **old line number** (left) and **new line number** (right). A blank column means the line doesn't exist on that side — additions have no old line number, deletions have no new line number. These numbers are used directly for `lineRefs` in key changes (see Step 3d).

`commits.txt` contains `git log --oneline` output for prologue context.

## Step 3 — Cluster + narrate

Using the hunks from `hunks.txt`, produce a `chapters` array. Each chapter groups related hunks into a coherent story beat, narrates them for a reviewer unfamiliar with this part of the codebase, and flags judgment calls that need human input.

### 3a — Clustering rules

Group hunks by **causal relationship** — changes that set up or enable later changes belong together.

- Spanning multiple files is expected and correct (e.g., schema + API + UI for one feature = one chapter).
- Moves and refactors are a single chapter — when code is removed from one file and added to another (or a file is deleted and a similar one created), group the deletion and addition hunks together as one "Move/Refactor" chapter, not separate "Remove" and "Add" chapters.
- Split only when changes are truly independent — a reviewer could understand one without knowing about the other.
- Tests belong with their implementation chapter.
- Config/dependency changes can be their own chapter if unrelated to a feature chapter.

**Chapter ordering:**

1. Foundation first: types, interfaces, schemas, utilities that others depend on
2. Core logic next: main implementation
3. Integration last: wiring, configuration, tests

Consider symbol dependencies between chapters — a chapter that introduces a type another chapter uses must come first.

**Hunk ordering within a chapter:**

- Group all hunks from the same file together — do not interleave hunks from different files.
- Within the same file, list hunks in ascending `oldStart` order (matching file layout).

### 3b — Self-validation rules

Every hunk in the formatted diff **must** appear in exactly one chapter. No hunk may be omitted and no hunk may appear in more than one chapter.

Each hunk header in the prep output has the format:
```
=== File: <path> (<status>) | filePath: "<path>", oldStart: <N> ===
```

Use the `filePath` and `oldStart` values from these headers to build `hunkRefs`.

`stagereview show` validates hunk coverage automatically — it will error with a list of missing or extra hunks if the chapters don't account for every hunk in the diff. If this happens, fix the chapters and retry.

### 3c — Narration rules

Write each chapter as a story beat — a meaningful step that moves the branch forward, not a summary of files changed.

- **Title:** action-oriented verb phrase, max 8 words (e.g., "Wire org ID through the API layer"). No filler like "Add support for".
- **Summary:** 2–3 sentences covering what this chapter enables and why. Lead with impact, then connect to the broader purpose. When a chapter builds on a previous one, open with that causal link explicitly (e.g., "Now that X is in place…").
  - Keep paragraphs short. Prefer splitting distinct points into separate short paragraphs (separated by a blank line) rather than writing one long dense paragraph. Each paragraph should convey a single idea.
  - Markdown allowed: `**bold**` for emphasis, `*italics*` for nuance, `` `backticks` `` for inline code references, and fenced code blocks when a short snippet (≤ 6 lines) helps illustrate the change.

### 3d — Key change rules

Key changes are **judgment calls only a human reviewer can make** — things that require product context, team conventions, or knowledge of the author's intent. Linters, type checkers, and code-review bots already cover correctness and style; skip anything they can catch. Ignore auto-generated files.

Return an **empty array** when nothing needs human input — do **not** invent items to fill the list. When a chapter is a straight