diffity-tour

What this skill does

# Diffity Tour Skill

You are creating a guided code tour — a narrated, step-by-step walkthrough of the codebase that answers the user's question or explains how a feature works. The tour opens in the browser with a sidebar showing the narrative and highlighted code sections.

## Arguments

- `question` (required): The user's question, topic, concept, or a GitHub PR URL. Examples:
  - `/diffity-tour how does authentication work?`
  - `/diffity-tour explain the request lifecycle`
  - `/diffity-tour how are comments stored and retrieved?`
  - `/diffity-tour closures`
  - `/diffity-tour React hooks`
  - `/diffity-tour walk me through this branch before I merge`
  - `/diffity-tour https://github.com/owner/repo/pull/123`

When the argument is a **GitHub PR URL** (matching `github.com/owner/repo/pull/N`), the tour is automatically locked to **Review mode** — the PR's diff drives the scope, and the conclusion must include a PR-flags list. See the **Review tours** section below.

## CLI Reference

```
{{binary}} agent tour-start --topic "<text>" [--body "<text>"] --json
{{binary}} agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json
{{binary}} agent tour-done --tour <id> --json
{{binary}} list --json
```

## Prerequisites

1. Check that `{{binary}}` is available: run `which {{binary}}`. If not found, {{install_hint}}.
2. **If the argument is a GitHub PR URL**:
   - Check `gh` is installed and authenticated: run `gh auth status`. If not authenticated, stop and ask the user to run `gh auth login`.
   - Verify the current repo matches the PR's repo: run `gh repo view --json nameWithOwner -q .nameWithOwner` and confirm it matches the `owner/repo` in the URL. If it doesn't, stop and tell the user they need to be inside the PR's repository clone — diffity can't tour a PR for a repo you don't have checked out.
   - Start diffity against the PR: run `{{binary}} --no-open <pr-url>` using the Bash tool with `run_in_background: true`. **The `--no-open` flag must come BEFORE the URL** — commander's `passThroughOptions()` will slurp any flag that appears after the positional URL into the refs array, skipping PR handling and producing an "unknown ref" error. This command checks out the PR's branch locally and starts a diff-scoped session. Wait 2 seconds, then run `{{binary}} list --json` to get the port. You do **not** also need a tree instance — the diff session supports `agent tour-*` commands.
3. **Otherwise**, ensure a tree instance is running: run `{{binary}} list --json`.
   - If no instance is running, start one: run `{{binary}} tree --no-open` using the Bash tool with `run_in_background: true`, wait 2 seconds, then run `{{binary}} list --json` to get the port.

## Instructions

### Pick a mode first

Before doing anything else, decide which mode this tour belongs to. The rest of the skill branches on this choice — scope, research method, and output shape all differ by mode. Do this before any tool calls.

**Shortcut:** if the argument is a GitHub PR URL (matches `github.com/owner/repo/pull/N`), skip the decision — it is locked to **Review mode**.

| Mode | Use when the user asks... | Scoped by | Target steps |
|---|---|---|---|
| **Focused** | a narrow "how does X work?" question | one code path | 3-6 |
| **Feature** | "how does this feature work?" | a feature boundary | 6-10 |
| **System** | "how does the whole thing work?" | architecture | 8-15 |
| **Concept** | about a programming concept | examples in the code | 3-8 |
| **Review** | to audit a branch/PR/feature before merge | `git diff <base>..HEAD` | variable — cover every meaningful change |

Trigger words that steer toward each mode:
- **Focused**: "how does X validate", "walk me through the Y endpoint"
- **Feature**: "how does authentication work", "explain the comment system"
- **System**: "how does the app work", "give me the architecture overview"
- **Concept**: concept names on their own (`closures`, `React hooks`, `async/await`, `generics`)
- **Review**: "before I merge", "review this branch", "walk me through the whole feature", "audit this PR", "I'm about to merge"

If multiple modes fit, prefer the more specific one (Review > Concept > Focused > Feature > System). If you genuinely can't tell which the user wants, ask before researching — don't guess and produce the wrong tour shape.

Mode changes which sections of this skill apply:
- **Concept mode** → read the **Concept tours** section below; research differs (search for examples, not follow a flow) and so does step progression.
- **Review mode** → read the **Review tours** section below; scoping is diff-driven, threads are walked one at a time, and the conclusion must include a PR-flags list.
- **Focused / Feature / System mode** → the default Phase 1-3 instructions apply directly.

### Phase 1: Scope and research

Before creating any tour steps, you must deeply understand the answer to the user's question.

1. **Confirm the scope.** The mode you picked sets a rough step count (see **Pick a mode** above). If the user's question is too broad to fit at that size (e.g. "explain everything" landing in System mode), mentally narrow to the most important aspect and state in the intro what you're covering and what you're leaving out.

2. **Identify the audience.** Consider how the question was phrased:
   - "How does X work?" → assume someone **new to this codebase** — explain architectural decisions, not just code mechanics
   - "Why does X do Y?" → assume someone **debugging or reviewing** — focus on the reasoning and edge cases
   - "Walk me through X" → assume someone who wants the **full picture** — be thorough, include context

3. **Research the codebase.** Read the relevant source files thoroughly. Follow the code path from entry point to completion.

   For review tours especially, also read `git log --reverse <base>..HEAD` and open any commit whose message describes a non-obvious fix, refactor, or defensive change. The author's own narrative is often the best source of *why* — far better than inferring intent from the code alone. Quote or paraphrase commit reasoning in step bodies where it illuminates a design decision (e.g. "commit `abc1234` introduced this check after a production incident where...").

   **When touring a GitHub PR, use `gh` for metadata and diff:**
   - `gh pr view <url> --json title,body,baseRefName,headRefName,commits,files` — PR title, body, base/head branches, commit list, and changed-file list. The PR **body** often contains the richest "why" (design context, screenshots, trade-offs the author considered) — quote or summarize it in the intro.
   - `gh pr diff <url>` — the unified diff that defines the tour's scope. Use this to confirm the full surface area, not just what you see in `git diff`.
   - Use the PR's `baseRefName` (from the JSON above) as the diff base — not `master`/`main` by default. Commands like `git log --reverse <baseRefName>..<headRefName>` walk the PR's commits in author order.
   - Source files are readable from the working tree because `{{binary}} <pr-url>` has already checked out the PR branch locally.

4. **Identify the key locations** that tell the story — the files and line ranges that someone needs to see to understand the answer.

5. **Note configuration dependencies.** If the behavior changes based on environment variables, feature flags, config files, or runtime conditions, note these. They must be called out in the tour so the reader understands "this is what happens when X is configured, but if Y were set instead, the flow would differ here."

6. **Plan a logical sequence** of steps that builds understanding progressively. Each step should lead naturally to the next.

**Guidelines for choosing steps:**
- Start at the real entry point — where external input arrives (HTTP route, CLI command, scheduled job, webhook). Config, schemas, constants, and helper functions are **not** entry points; they are dependencies of the flow.
-