Diffity Tour

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.

1. 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.

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.

1. 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

1. 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.

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

1. 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."

1. 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.