code-tour

Create persona-targeted, file-anchored code tours

A great tour is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Every file path and line number must be real and verified.

Persona selection

Infer silently from the request:

User says	Persona	Depth
"tour for this PR"	pr-reviewer	standard
"why did X break" / "RCA"	rca-investigator	standard
"onboarding" / "new joiner"	new-joiner	standard
"quick tour" / "vibe check"	vibecoder	quick
"architecture"	architect	deep
"security" / "auth review"	security-reviewer	standard
(no qualifier)	new-joiner	standard

Depth guidelines:

• Quick: 5–8 steps, high-level, 1–2 sentences per step.
• Standard: 10–20 steps, full narrative, 3–5 sentences per step.
• Deep: 20–40 steps, links between steps, covers edge cases and design rationale.

Tour file format

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Tour title — persona",
  "description": "One sentence: what this tour covers and who it's for.",
  "steps": [
    {
      "file": "src/index.ts",
      "line": 1,
      "title": "Entry point",
      "description": "The application starts here. The `main()` function wires together the three primary subsystems..."
    }
  ]
}

Tours live in .tours/<name>.tour in the repo root.

Markdown fallback. The .tour JSON is the primary output. When the CodeTour extension or VS Code isn't available (CI, a headless agent, a reviewer reading on GitHub), also emit — or fall back to — a plain-markdown version: a numbered list of path/to/file.ts:42 — one-line description of what happens here, one entry per step, in the same order as the tour. It carries the same narrative and is readable anywhere, so the tour is never blocked on a specific editor being installed.

Step writing principles

1. Start with the entry point. Request handling / server startup / CLI entry / main module — wherever execution begins.
2. Follow the call graph. Each step ends by saying where the tour goes next and why. No teleporting.
3. Name what matters. Call out non-obvious decisions ("this uses a singleton because…"); don't describe what the code literally says.
4. Speaker notes for complexity. For a step covering a subtle invariant, write it as if you're pair-programming — "Watch out for X here because Y."
5. End with a summary step. "You've seen the full request lifecycle. The key files are A, B, and C. Start with A when you need to change X."