Code Tour

Code Tour

Create CodeTour .tour files for codebase walkthroughs that open directly to real files and line ranges. Tours live in .tours/ and are meant for the CodeTour format, not ad hoc Markdown notes.

A good tour is a narrative for a specific reader: what they are looking at, why it matters, and what path to follow next.

Only create .tour JSON files. Do not modify source code.

When to Use

• User asks for a code tour, onboarding tour, architecture walkthrough, or PR tour
• User says "explain how X works" and wants a reusable guided artifact
• Onboarding a new maintainer or reviewer
• Documenting an RCA failure path or security trust boundary

When NOT to Use

Workflow

1. Discover

Explore the repo before writing anything:

• README and entry points
• Folder structure and key config files
• Changed files if PR-focused

Do not start writing steps before understanding the code shape.

2. Infer the reader persona

3. Verify anchors

Every file path and line anchor must be real:

• Confirm the file exists (glob / grep)
• Confirm line numbers are in range (view with view_range)
• Never guess line numbers

4. Write the .tour file

Output path: .tours/<persona>-<focus>.tour

{
  "title": "<Tour Title>",
  "description": "<One sentence: who this tour is for and what it covers>",
  "steps": [
    {
      "file": "src/auth/middleware.ts",
      "line": 42,
      "title": "Auth Gate",
      "description": "Every protected request passes here first. Notice the early-return on missing tokens."
    },
    {
      "directory": "src/services",
      "title": "Service Layer",
      "description": "All business logic lives here — handlers delegate immediately to these services."
    },
    {
      "file": "src/core/pipeline.ts",
      "selection": {
        "start": { "line": 15, "character": 0 },
        "end": { "line": 34, "character": 0 }
      },
      "title": "Request Pipeline",
      "description": "The 5-stage pipeline that every request traverses."
    }
  ]
}

5. Validate before finishing

• Every referenced path exists
• Every line or selection is in range
• First step is anchored to a real file or directory (not content-only)
• Tour tells a coherent story, not just a file list

Step Types

See Also

• doc-update — prose documentation updates
• pr-multi-perspective-review — review a PR from multiple lenses