Code Tour

Code Tour

A guided path through a codebase, ordered so each stop makes the next one legible, and annotated with why the code is the way it is rather than what it does. The what is already on screen; the why is what takes a new engineer three weeks to reconstruct and what the person who knows it will lose in six months. Tours rot faster than any other documentation because they point at line numbers, so anchoring and validation are half this skill.

When to use this skill

• Onboarding an engineer onto a service where reading order determines whether week one is productive or archaeological
• Handing off ownership of a system before its author changes team or leaves
• Explaining a subsystem ahead of a design review, so reviewers arrive with shared context
• Documenting a surprising design whose rationale lives only in a closed pull request
• Auditing an existing tour that has silently rotted as files moved and functions were renamed
• Re-entering your own code after six months away, which is functionally the same problem as onboarding

Inputs the skill expects

• The repository root, and which directories are vendored or generated
• The audience and their starting knowledge — a backend engineer and a frontend engineer need different first stops
• The one question the tour must leave answered ("how does a request become a row?")
• Time budget, which sets the stop count more than anything else
• The design decisions worth explaining, especially the ones that look wrong at first glance
• An existing tour definition, when validating or updating rather than authoring

Clarify First

Before building the tour, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• The question the tour answers — a tour of "the codebase" has no ordering principle; a tour of "how a request becomes a row" orders itself
• Audience and their existing knowledge — decides which stops can be skipped and which concepts need a stop of their own
• Time budget — 30 minutes is 5-7 stops; anything longer gets abandoned midway and never resumed
• Which decisions are worth explaining — the why-notes are the entire value; without them the tour is a file listing

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Propose candidate stops from the repository

1. Run the analyzer against the repo root, excluding vendored and generated directories.
2. Read the ranked candidates. Entry points come first, then config and boundaries, then high-fan-in internals — that ordering is the analyzer's opinion about reading order.
3. Cut ruthlessly. Any candidate you cannot write a "why it is this way" note for is a file, not a stop.
4. Add stops the analyzer cannot see: the surprising workaround, the module that looks redundant and is not, the abstraction whose absence would be worse.

python3 engineering/code-tour/scripts/tour_propose.py \
  --repo . --max-stops 7 --exclude vendor --exclude generated --format text

Fan-in for Python comes from the AST import graph and is reliable. For other languages it is a filename-reference heuristic and will over-count common names — treat those scores as a ranked shortlist to review, not a verdict.

Workflow 2 — Write the tour and audit the notes

1. Fill in each stop's note, question, and gotcha in the tour JSON. The note explains why; the question forces the reader to look at the code before moving on.
2. Anchor every stop to a symbol name, not a line number. Line numbers are recorded for convenience but resolved from the symbol on every validation.
3. Run the renderer's audit. It flags notes that only restate what the code does, notes under 20 words, and notes with no causal language.
4. Render the document once the why-ratio clears 0.8.

python3 engineering/code-tour/scripts/tour_render.py \
  --input engineering/code-tour/assets/sample_tour.json \
  --audit-only --min-why-ratio 0.8 --format text

The shipped sample scores 83% — stop 5 fails deliberately, so you can see what a what-only note looks like next to four that explain why.

Workflow 3 — Validate the tour against the current tree

1. Run validation before every use of the tour, and in CI on the branch that owns the code.
2. Read the statuses: deleted and moved are broken, drifted means the anchor's body changed and the note may now be wrong, shifted is cosmetic line movement.
3. For moved anchors, take the suggested relocations — they come from searching the tree for the anchor name.
4. Re-freeze line numbers and fingerprints with --update once you have re-read the drifted notes.

python3 engineering/code-tour/scripts/tour_validate.py \
  --tour engineering/code-tour/assets/sample_tour.json \
  --repo engineering/code-tour --format text

Stop paths are relative to the tour's own repo root, so --repo points at the package the tour describes — here, this skill itself. Exit code is 1 when any stop is broken, which is what lets a tour live in CI. The shipped sample exits 1 on purpose: stop 6 points at a scripts/tour_export.py that was never shipped.

Decision frameworks

Choosing the first stop [PROVEN]

The first stop determines whether the reader builds a mental model or a list of facts.

Never open on the data model. It is where authors want to start, because it is where the domain lives, and it is where readers stall — a schema without a flow through it is a vocabulary list.

Stop count by time budget [RECOMMENDED]

Beyond ten stops readers stop retaining and start skimming, and a skimmed tour teaches less than a well-chosen five-stop one. If the system genuinely needs fifteen stops, that is two tours with different questions, not one long one.

Anchoring strategy — what rots and what does not

The tour format records line but resolves from anchor. A tour anchored on line numbers is broken by the next unrelated edit above it, which is why most tours in the wild are broken within a month of being written.