Skill — Code Tour

When this skill activates

When generating guided explorations of a codebase to help someone understand its architecture, data flow, or implementation patterns. Use when onboarding new team members, documenting complex subsystems, or creating learning paths through unfamiliar code.

A code tour is NOT a README or API reference — it is a narrative journey through source files in a deliberate order, with annotations explaining the "why" at each stop, building understanding progressively.

Mandatory actions when this skill is active

Before generating the tour

1. Determine tour scope and audience:

• Who is this tour for? (new hire, external contributor, senior dev in new area)
• What should they understand after completing the tour?
• What prior knowledge can be assumed?
• Scope: full system overview vs focused subsystem deep-dive

1. Map the dependency graph:

• Identify the entry point(s) — main, index, app, CLI handler
• Trace first-level imports from the entry point
• Identify core modules vs utility/helper modules
• Note circular dependencies or surprising coupling

1. Select a tour strategy:

1. Plan the stop sequence:

• 8-15 stops is ideal (fewer feels shallow, more causes fatigue)
• Each stop should build on the previous one
• Alternate between "big picture" and "zoom in" stops
• End with a synthesis stop that ties everything together

During tour generation

Stop format (mandatory for each stop):

## Stop N: [Descriptive Title]

**File:** `src/path/to/file.ts` (lines 42-87)

**Why this file matters:**
[1-2 sentences on this file's role in the system]

**What to notice:**
- [Key pattern, design decision, or technique used here]
- [Relationship to previous stop]
- [Any non-obvious behavior or convention]

**Key code:**

// The critical section, with inline annotations function handleRequest(ctx: Context) { // Notice: middleware chain is resolved here, not at registration time const pipeline = ctx.middleware.resolve(); // ... }

**Checkpoint:** After this stop, you should understand:
- [Concrete understanding goal 1]
- [Concrete understanding goal 2]

Progressive complexity rules:

• Stop 1-3: Configuration, entry points, "what runs when the app starts"
• Stop 4-7: Core business logic, primary data flow, key abstractions
• Stop 8-10: Edge cases, error handling, performance-critical paths
• Stop 11+: Advanced patterns, extension points, testing infrastructure

Annotation principles:

• Explain WHY this code exists, not WHAT it does (the code shows what)
• Highlight design decisions: "This uses X pattern because..."
• Call out conventions: "All handlers in this project follow this shape..."
• Note historical context if relevant: "This was refactored from X because..."
• Flag potential confusion points: "This looks like X but is actually Y because..."

Connecting stops:

• Each stop after the first must reference how it relates to previous stops
• Use phrases like: "Remember the middleware we saw in Stop 3? This is where..."
• Draw the thread of data/control flow between stops explicitly
• If stops are non-linear, explain why you're jumping to this location

After tour generation

1. Add a tour summary:

   ## Tour Summary

   **Total stops:** N
   **Estimated reading time:** ~X minutes
   **Key takeaways:**
   1. [Most important architectural insight]
   2. [Critical pattern used throughout]
   3. [Key design decision and its rationale]

   **Suggested next tours:**
   - [Related subsystem that builds on this understanding]
   - [Deeper dive into one area touched here]

1. Verify tour coherence:

• Read through all stops sequentially — does the narrative flow?
• Does each checkpoint build on the previous one?
• Would the target audience actually understand this?
• Are file paths and line numbers accurate and current?

1. Output format:

• Single markdown file: TOUR-[name].md in the project root or docs/tours/
• Include a table of contents with links to each stop
• If the tour references specific commits or versions, note the git ref

Self-check before task completion

Before marking a code tour task done:

• [ ] Did I identify the target audience and their prior knowledge level?
• [ ] Did I select an appropriate tour strategy for the scope?
• [ ] Does the tour have 8-15 stops with progressive complexity?
• [ ] Does every stop include: file path, why it matters, what to notice, checkpoint?
• [ ] Does the narrative flow logically from one stop to the next?
• [ ] Are file paths and line references accurate to the current codebase?
• [ ] Did I include a summary with key takeaways and suggested next tours?
• [ ] Would the target audience actually learn what they need from this tour?