Tour Guide

Create a guided repository tour for this learning goal:

$ARGUMENTS

Your job is to research the codebase, choose the best tour stops, then present them ONE AT A TIME while building a persistent tour document with Mermaid diagrams.

Process:

1. Research the codebase: identify the main concepts, flows, or components relevant to the user's learning goal. Use the Agent tool with subagent_type "Explore" if needed.
2. Find the strongest entry points. Prefer implementation files, tests, config, and docs that clarify how the system works.
3. Build a tour plan with a reasonable number of stops, ordered from foundational context / entry points to deeper detail.
4. Choose a short kebab-case tour name derived from the learning goal (e.g. "modular-arithmetic", "auth-flow").
5. Create the tour file at .claude/tours/{tour-name}.md with the initial header (use Bash to mkdir -p .claude/tours first). The file should start with:

# Tour: {Tour Title}

> {One-sentence learning goal}
>
> Date: {YYYY-MM-DD}
> Stops: {N planned}

## Overview

```mermaid
graph TD
S1["Stop 1: Title"] --> S2["Stop 2: Title"]
S2 --> S3["Stop 3: Title"]
...
```

(The overview diagram shows the full tour route as a simple flow.)

6. Present the tour goal, the planned stops (titles only), and the overview diagram to the user.
7. Then present ONLY the first stop:
   • Open the file in VS Code with code -r -g '<file>:<line>'
   • Show the stop number, title, file path, and line number
   • Explain why this stop matters and what to pay attention to
   • End with: "Press Enter to continue to the next stop, or type a question / direction to explore."
8. After presenting each stop, append it to the tour file using Edit. Each stop entry should include:
   • The stop heading, file path, and explanation
   • A Mermaid diagram that illustrates what was learned at this stop. Choose the most descriptive diagram type for the content:
     • graph TD/LR for architectural relationships, module dependencies, data flow
     • classDiagram for type hierarchies, struct fields, trait implementations
     • sequenceDiagram for call chains, request flows, protocol steps
     • stateDiagram-v2 for state machines, lifecycle transitions
     • flowchart for algorithms, decision trees, control flow
   • The diagram should focus on what THIS stop reveals, not repeat prior diagrams.
   • Also update the overview diagram to highlight the current stop (e.g. mark visited stops with a different style).
9. STOP and wait for the user to respond. Do NOT present the next stop until the user sends a message.
10. When the user continues (Enter, "next", "continue", or any short acknowledgment), present the next stop the same way.
11. If the user asks a question or wants to explore a different angle, answer or adjust the tour accordingly.
12. After the final stop, append a summary section to the tour file and suggest follow-up questions.

Rules:

• CRITICAL: Only show ONE stop per message. Wait for user input before advancing.
• CRITICAL: Update the tour file after EVERY stop. The file should always reflect progress so far.
• Do not pick duplicate or near-duplicate stops.
• Prefer the most specific useful line, not just the top of the file.
• Keep the route coherent and minimize context switching.
• If tests explain behavior better than implementation, include them.
• If the repository does not contain enough information for a good tour, say that clearly and explain what is missing.
• If a stop depends on another stop, place the prerequisite earlier.
• Mermaid diagrams should be concise and readable (no more than ~15 nodes per diagram). Prefer clarity over completeness.

Stop format (shown to user):

Stop N/Total — Title

File: path/to/file.rs:LINE

Why this stop matters and what to pay attention to.

(diagram for this stop)

Press Enter to continue, or ask a question.

Tour file stop format (appended to .claude/tours/{tour-name}.md):

## Stop N — Title

**File:** [`path/to/file.rs:LINE`](path/to/file.rs)

Explanation of what this stop covers.

```mermaid
(diagram for this stop)
```

Final stop format (after the last stop):

Tour Complete

Brief summary of what was covered.

(A final "big picture" diagram that ties together the key concepts from the entire tour)

Next Questions

List 2 to 4 useful follow-up questions the user could ask next.