Create a guided code tour that walks through the codebase to answer a question or explain a feature. Opens in the browser with step-by-step navigation and highlighted code.

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 Prerequisites 1. Check that diffity is available: run which diffity . If not found, install it with npm install g diffity . 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 diffity 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 diffity 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 diffity list json . If no instance is running, start one: run diffity tree no open using the Bash tool with run in background: true , wait 2 seconds, then run diffity 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 diffity <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. Introduce foundations just in time. When the flow first reads a schema, tour the schema. When it first calls a helper, tour the helper. When it first references a config value, tour the config. Do not front load a prelude of foundation pieces before the flow starts. At most one "orientation" step (e.g. a route table showing all endpoints) may precede the entry point. Everything else should be motivated by something the reader has just seen. Follow the execution path in the order things actually happen. Include only locations that are essential to understanding — skip boilerplate. End at the final outcome (response sent, data persisted, UI rendered). Each step should cover a single concept or code section. Include concrete examples where possible (e.g. "when the user runs diffity main , this becomes..."). Top down, not bottom up. A tour mirrors how the code runs at runtime, not how it was built. Do not walk config → schema → helpers → routes → actions. Walk route → action → (schema appears here because a query reads it) → (config appears here because a handler references it) → (helper appears here because something calls it). Readers retain context better when each new piece is introduced at the moment it becomes relevant. The reader should feel they're sitting next to you as you trace a real request, not sitting through a lecture about architecture before the demo starts. Handling cross module flows: When the code path crosses into a library, utility module, or deeply nested abstraction, decide whether to follow it: Follow it if the logic there is essential to understanding the answer (e.g. a custom middleware that transforms the request) Summarize it if the module does something standard or well known (e.g. "this calls the Express router, which matches the path and invokes our handler") — mention what it does in the step body without creating a separate step for it Skip it if it's pure boilerplate or plumbing (e.g. re exports, type only files) Patterns applied across many files. When a single change is replicated across N similar call sites (e.g. the same guard added to 8 handlers, the same middleware registered on every route), do not make N steps. Make one step on the most representative file with full context, then list the other call sites as goto links in the body ("the same guard is also added to X, Y, Z"). One concept, one step — the tour should teach the reader the pattern once, not N times. The exception: if one of the applications is subtly different from the others (e.g. called twice in a transfer flow, or with different args), spend a separate step on that one. Phase 2: Create the tour The tour UI has a dedicated explanation panel. The intro (from tour start body ) is displayed as step 0 — the first thing the reader sees, filling the full panel. Each subsequent step shows its narrative in the same panel alongside the highlighted code. Since the panel has generous space, write rich, detailed explanations. 1. Start the tour with a short topic title and introductory body: The topic is displayed in the tour panel header — keep it to 3–6 words (e.g. "Authentication Flow", "How Routing Works", "Comment System Architecture"). Do NOT use the user's full question as the topic. Writing the intro body (step 0): This is the first thing the reader sees and it fills the entire explanation panel. Use this space for a thorough architectural overview that sets up everything the reader needs before diving into code. Include: The key components/packages/modules involved and their responsibilities How they connect — data flow, call chains, or dependency relationships Key abstractions or patterns the reader should know about A summary flow diagram using bold text (e.g. CLI args → git diff → parser → JSON API → React render ) Configuration context — if the feature's behavior depends on config, environment variables, or feature flags, mention them here so the reader knows what mode/state the tour assumes If you scoped down a broad question, state what you're covering: "This tour focuses on the OAuth login flow. Token refresh and session management are related but covered separately." Use rich markdown formatting — paragraphs, bold, code , tables, code blocks. This is not a table of contents of what the tour will

diffity-tour