build-replication-playbook

What this skill does

# Build Replication Playbook (Interactive HTML)

Document a multi-step collaborative build as a teaching artifact: the repeatable recipe,
a decision-by-decision timeline (each question and the user's answer), and **real**
per-round timing extracted from the session transcript — not guessed. Output is one
light, tabbed, self-contained HTML file.

## When to use

- The user wants to teach others to replicate a process they just went through.
- The user wants an honest after-action record of a build, including the time it cost.
- A long collaborative session reached a milestone worth codifying.

## Why it works

A good playbook captures both *what was decided* and *what it cost*. The decision log
makes the path reproducible; transcript-sourced timing keeps it honest instead of
flattering. The recipe is what actually transfers to the next person.

## Workflow

1. **Reconstruct the decision log** from the conversation: every fork, the options that
   were offered, and the choice the user made (including any the user reframed themselves).
2. **Distill the transferable recipe** — the ordered moves that took the project from
   nothing to done — plus do / avoid teaching tips drawn from what actually went right and
   wrong (e.g. a tool that did not exist, a too-dense first draft, a stray artifact).
3. **Pull REAL timing with the bundled script.** Locate the session transcript `.jsonl`
   and run:
   ```bash
   python3 scripts/transcript_timing.py <path-to-session-transcript.jsonl>
   ```
   It reports per-round active-work vs idle gaps and totals. It counts only **genuine user
   turns** — entries of type `user` that are prompt-bearing (`promptId` present) AND whose
   content is plain text, not a tool-result block. The content-shape check is what excludes
   tool-result carriers: they share the SAME `promptId` as the prompt that spawned the round,
   so `promptId` alone does not distinguish them. Transcripts usually live at
   `~/.claude*/projects/<cwd-with-slashes-as-dashes>/<session-id>.jsonl`.
   **Never fabricate timing** — if the transcript is unavailable, say so in the playbook.
4. **Build one self-contained HTML** per `../_shared/single-file-html-conventions.md`
   (inline CSS/JS, no deps, light/dark), written into the repo (usually `docs/`).
5. **Render as tabs:** *Recipe · What happened · Timing · Teach it.*
   - **Recipe:** the ordered moves as numbered steps, each with a one-line "technique" tag.
   - **What happened:** a vertical timeline; one event per decision with the question and
     the user's answer; color-code step vs. decision vs. review vs. detour.
   - **Timing:** a few big-number stats (net active, wall-clock, automated portions), a
     per-round table, and honest caveats (multiple-choice answers look instant;
     background-job waits inflate a round's "active" span).
   - **Teach it:** do / avoid lists + a suggested session shape and rough time budget.
6. **Keep it light** — same density discipline as a usage guide (short phrases, one panel
   at a time). Rebuild lighter if it reads like a wall of text.

## Honesty rules

- Timing comes from the transcript, never from memory or estimate. State the caveats the
  script prints (instant-looking multiple-choice rounds; background waits counted as active).
- Record real missteps in "Teach it" (assumed-but-missing tools, density misses, stray
  files from unrelated commands) — they are the most useful lessons.

## Resources

- **`scripts/transcript_timing.py`** — extracts per-round active/idle timing from a
  session `.jsonl`. Run it; paste its numbers into the Timing tab.
- **`../_shared/single-file-html-conventions.md`** — the shared single-file HTML technique.
- **`references/structure.md`** — the four-tab layout, the timeline event schema, and the
  timing-stat presentation.

## Pitfalls

- Do not guess durations — run the script or omit timing and say why.
- Do not turn it into a build log of implementation detail; it is a *teaching* artifact —
  decisions and recipe over code.
- Do not present background-job wait time as if it were hands-on effort; label it.