| name | transcript-narrative |
| description | Produce a narrative case study / annotated timeline from Claude Code session transcripts — verbatim prompts, phase buckets, quantitative metrics, extracted lessons. For raw quantitative metrics use transcript-analysis. |
Step 1 — Scope the analysis
Identify the branches, session date-range, and repos in play. Use buckets to enumerate branches and per-branch models:
python3 ~/.claude/scripts/transcript-analysis.py buckets
Note the branch names — you will pass them to later subcommands via --branches <branch>.
Step 2 — Extract verbatim user turns
Read the session JSONL transcripts at ~/.claude/projects/*/. Each file is one session. Filter to turns where:
role == "user"isSidechain is absent or false — exclude subagent/sidechain turns entirely
Capture BOTH opening prompts AND mid-session steering turns. Later corrective or redirecting turns are often as instructive as the opener.
For each qualifying turn, record:
- Session ID and timestamp
message.content[].text — the verbatim prompt text
Do not vendor a script for this extraction. Read the JSONL directly with the Read tool or a short inline shell expression, filtering by the criteria above.
Step 3 — Bucket prompts into phases and build an annotated timeline
Group the extracted turns by branch and investigative phase. For each phase, record:
| Field | Source |
|---|
| Date range | Timestamps from Step 2 turns |
| Session count | Count of distinct session IDs in the phase |
| Active minutes | duration --branches <branch> → Active(min) column |
| Artifact produced | PR number or branch name |
| 1–3 most consequential verbatim prompts | Selected from Step 2 extractions |
Prefer prompts that represent a decision point, a course-correction, or a constraint the model had to internalize — not routine status checks.
Step 4 — Cross-reference quantitative metrics
Run these subcommands and include their output as a quantitative appendix that grounds the narrative:
python3 ~/.claude/scripts/transcript-analysis.py fail-seq --branches <branch>
python3 ~/.claude/scripts/transcript-analysis.py duration --branches <branch>
python3 ~/.claude/scripts/transcript-analysis.py subagents --branches <branch>
python3 ~/.claude/scripts/transcript-analysis.py pr-link --repo owner/repo --branches <branch>
python3 ~/.claude/scripts/transcript-analysis.py review-trace
For fail-seq interpretation: a spike followed by zeros is convergent (expected); oscillation with no sustained run of zeros is thrashing (flag for the lessons step). See transcript-analysis for the full reading guide.
Step 5 — Redact before sharing
Quoted prompts come from direct JSONL extraction in Step 2 — the CLI's --redact flag is available only on audit-routing and does not touch them. Before publishing to any shared or public surface:
- Manually scan every quoted prompt for customer PII and credentials
- For the quantitative appendix, use
audit-routing --redact to anonymize project-dir names when posting output to GitHub issues or external surfaces
Step 6 — Extract lessons, ranked by prompt-arc visibility
Distill lessons from the annotated timeline. For each lesson:
- Tie it to the verbatim prompt arc that surfaced it (cite the phase and the specific prompt)
- Rank by how clearly the lesson appears in the evidence — lessons with a direct, traceable prompt arc rank above those inferred from metrics alone
For raw quantitative metrics without narrative synthesis, use transcript-analysis — the two skills are designed to be used together.
