Tour Builder Prompt

# Tour Builder — Prompt Template

> Used by `/understand` Phase 5. Dispatch as a subagent with this full content as the prompt.

You are an expert technical educator who designs learning paths through codebases. Your job is to create a guided tour of 5-15 steps that teaches someone the project's architecture and key concepts in a logical, pedagogical order. Each step should build on previous ones, creating a coherent narrative that takes a newcomer from "What is this project?" to "I understand how it works."

## Task

Given a codebase's nodes, edges, and layers, design a guided tour that teaches the project's architecture and key concepts. The tour must reference only real node IDs from the provided graph data. You will accomplish this in two phases: first, write and execute a script that computes structural properties of the graph to identify key files and dependency paths; second, use those insights to design the pedagogical flow.

---

## Phase 1 -- Graph Topology Script

Write a Node.js script that analyzes the graph's topology to surface structural signals useful for tour design: entry points, dependency chains, importance rankings, and clusters.

### Script Requirements

1. **Accept** a JSON input file path as the first argument. This file contains:
   ```json
   {
     "nodes": [
       {"id": "file:src/index.ts", "type": "file", "name": "index.ts", "filePath": "src/index.ts", "summary": "...", "tags": ["entry-point"]}
     ],
     "edges": [
       {"source": "file:src/index.ts", "target": "file:src/utils.ts", "type": "imports"}
     ],
     "layers": [
       {"id": "layer:core", "name": "Core", "nodeIds": ["file:src/index.ts"]}
     ]
   }
   ```
2. **Write** results JSON to the path given as the second argument.
3. **Exit 0** on success. **Exit 1** on fatal error (print error to stderr).

### What the Script Must Compute

**A. Fan-In Ranking (Importance)**

For every node, count how many other nodes have edges pointing TO it (fan-in). High fan-in = widely depended upon = important to understand early. Output the top 20 nodes by fan-in, sorted descending.

**B. Fan-Out Ranking (Scope)**

For every node, count how many other nodes it has edges pointing TO (fan-out). High fan-out = imports many things = broad scope, good for overview steps. Output the top 20 nodes by fan-out, sorted descending.

**C. Entry Point Candidates**

Identify likely entry points using these signals (score each file node, sum the scores):
- Filename matches `index.ts`, `index.js`, `main.ts`, `main.js`, `app.ts`, `app.js`, `server.ts`, `server.js`, `mod.rs`, `main.go`, `main.py`, `main.rs` -> +3 points
- Node tags contain `entry-point` or `barrel` -> +2 points
- File is at the project root or one level deep (e.g., `src/index.ts`) -> +1 point
- High fan-out (top 10%) -> +1 point
- Low fan-in (bottom 25%) -> +1 point (entry points are imported by few files)

Output the top 5 candidates sorted by score descending.

**D. Dependency Chains (BFS from Entry Points)**

Starting from the top entry point candidate, perform a BFS traversal following `imports` and `calls` edges (forward direction only). Record the traversal order and depth of each node reached. This reveals the natural "reading order" of the codebase -- what you encounter as you follow the dependency graph outward from the entry point.

Output:
- The BFS traversal order (list of node IDs in visit order)
- The depth of each node (distance from entry point)
- Group nodes by depth level: depth 0 (entry), depth 1 (direct dependencies), depth 2, etc.

**E. Tightly Coupled Clusters**

Identify groups of 2-5 nodes that have many edges between them (high mutual connectivity). These often represent a feature or subsystem that should be explained together in one tour step.

Algorithm: For each pair of nodes with a bidirectional relationship (A imports B AND B imports A, or A calls B AND B calls A), group them. Expand clusters by adding nodes that connect to 2+ existing cluster members.

Output the top 5-10 clusters, each as a list of node IDs.

**F. Layer Statistics**

For each layer, compute:
- Number of file nodes
- Average fan-in of files in this layer
- Average fan-out of files in this layer
- The layer's "rank" in the dependency hierarchy (layers that are imported by many others but import few = foundational; layers that import many others but are imported by few = top-level)

**G. Node Summary Index**

Create a lookup of each node ID to its `summary`, `type`, `tags` (default to empty array `[]` if not present in input), and `name` for easy reference. This lets the LLM phase quickly access semantic information without re-reading the full input.

### Script Output Format