diff-tours

name	diff-tours
description	Create diff tours that narrate code changes to help reviewers understand PRs. Use when preparing a PR for review or when asked to document changes.

Diff Tours

Create structured documentation that walks reviewers through code changes. A diff tour combines a structured explanation of intent with focused diff hunks and context links.

When to Use

• Preparing a PR for review
• Documenting AI-generated code changes
• Creating a "walk me through this change" document
• Any multi-file change that benefits from narration

When NOT to Use

• Single-file, <50 line changes with obvious intent
• Pure documentation updates
• Trivial bug fixes where the diff is self-explanatory

Input

Accepts:

• PR URL or number
• Branch name
• Commit range (e.g., origin/main..HEAD)
• No input defaults to current branch vs main

Process

1. Gather changes

   git diff --name-status origin/main..HEAD
   git diff --stat origin/main..HEAD
   git log --reverse --oneline origin/main..HEAD
   

2. Choose organization (what serves reviewers best):

   • Commit-by-commit (when commits tell a clean story)
   • Topic/concern-based (for large refactors)
   • File-by-file (when files have clear hierarchy)
   • Risk-based (mixing critical with mechanical changes)

3. Draft the tour following the spec in references/diff-tours.md

4. For each section, decide:

   • Inline diff: Logic changes, security-sensitive code, novel patterns
   • Link-only: Mechanical changes, generated files, boilerplate

5. Add context links (required — enables tooling/viewer):

   • PRs: GitHub permalinks with commit SHA and line ranges
   • Local: src/path/file.ts:15-50
   • Always under a **Context:** label, one link per line

6. Scale appropriately:

   • Small PRs (<5 files): Summary + single walkthrough section is fine
   • Large PRs (20+ files): Detailed sections for critical changes, catch-all for the rest

Output Format

# Diff Tour: <title>

> **Goal:** <one sentence>
> **Range:** `origin/main..HEAD`

## Summary
- **Why:** <motivation>
- **What changed:** <2-5 bullets>

## Walkthrough

### 1) <section title>

**Intent:** <what and why>

**Context:** <permalink or file:line>

```diff
<focused hunk, 10-40 lines>
`` `

### 2) <next section>
...

Required Elements

• Title + Goal (one sentence)
• Summary with why and what changed
• Walkthrough with narrated changes and context links
• All changed files mentioned (even in catch-all section)
• Context links in every section (under **Context:** label)

Optional Sections (include when relevant)

• Risk assessment: Low/Medium/High with rationale
• Tests: How to run, what's covered, known gaps
• Ops/Rollout: Only if non-standard deployment needed
• User-visible impact: For user-facing changes
• Design decisions: Key choices and trade-offs
• Reviewer FAQ: Anticipated questions
• Verify checklist: Only for non-obvious invariants or edge cases

See references/diff-tours.md for full specification, examples, and format reference for tooling.

Sharing

After writing a diff tour, generate a shareable viewer link:

share.sh DIFF_TOUR.md

The share.sh script is bundled with this skill (see share.sh in the skill directory).

This compresses the tour into a URL fragment and outputs a link like:

go/diff-tour-viewer#tour=<compressed>

Paste this link in the PR description for one-click review. The tour loads entirely from the URL — no server, no auth, no CORS.

Requires: node (uses lz-string for compression, auto-installed on first run).