---
name: walkthrough
description: Guided walkthrough of code, a diff/PR, architecture, tests, or docs — build the reader's mental model, explain the choices made and their tradeoffs, and critically evaluate the artifact. Use when the user wants to understand or audit something rather than change it. Adapts to expert vs learner; companion to the pair skill.
---

# Walkthrough

Lead the user through an artifact so they genuinely understand it — and pressure-
test it as you go. You are a presenter-reviewer, not a narrator: surface the
choices, the tradeoffs, the risks, and where you'd push back. A walkthrough that
only describes is a worse `cat`.

> **Calibrate to expertise or you actively harm.** Detailed remedial explanation
> *helps* a novice and *hinders* an expert (the expertise-reversal effect). Match
> the audience dial: scaffold the learner, skip straight to deltas and risk for
> the expert. Over-explaining to an expert is a failure, not thoroughness.

Covers any artifact: source, diff/PR, architecture, API, data model, tests,
docs, build, deploy/ops flow, or a design doc.

## Dials

Set by the user, else inferred, else defaults:

```
/walkthrough audience=expert depth=deep
```

- **audience** — `expert` · `mixed` (default) · `learner` — the spine dial.
  - *expert*: start from architecture, invariants, risk, deltas. Highlight non-
    obvious coupling, edge cases, operational consequences, alternatives. Compact.
    Assume they resolve local syntax/framework details themselves. Lead with
    "here's where I'd push back."
  - *learner*: make tacit reasoning visible. Explain idioms at first use. Show a
    worked example before asking them to reason. Small checkpoints over lectures.
    **Fade** scaffolding as they demonstrate understanding.
  - *mixed*: explain the system map, not every syntax detail; offer optional
    deeper dives; watch for signals to add rigor or scaffolding and re-calibrate.
- **depth** — `skim` · `guided` (default) · `deep`: how far down the important
  path you trace — headline map only, the main path, or every branch and invariant.

## Loop

1. **Orient** — artifact, the user's goal, audience, what they already know.
2. **Map** — compact structure: entry points, components, data + control flow,
   dependencies, boundaries. The mental model before the details.
3. **Trace** — walk the important path at the chosen depth. Prefer *causal*
   explanation: what happens, why, what depends on it, what breaks if it changes.
4. **Explain the choices** — name the decisions the author/system made; give the
   likely motivation, the alternatives, the tradeoffs accepted.
5. **Challenge** — see below.
6. **Check understanding** — *only when learning is a goal* (see below).
7. **Record** — close with: what's sound, what's questionable, what should
   change, what's still uncertain.

## Challenge

Always on, calibrated — the same posture as the `pair` skill. Raise a *credible*
concern on correctness, maintainability, security, performance, observability,
testability, scope, architectural fit, migration risk, brittle abstraction, or
misleading docs. When you do: name it, state the consequence, offer an
alternative, mark blocker vs preference. Don't litigate trivia.

## Check understanding (learner / mixed only)

When the goal includes learning, use comprehension checks instead of just
telling — they're how the model transfers, not a quiz:

- predict before reveal ("what must this variable hold before you read on?")
- compare-and-contrast two approaches
- "what breaks if this changes?"
- ask them to name an invariant, or why an alternative was rejected

Never gratuitous. A check that doesn't improve comprehension just slows the
session — cut it. For an `expert` audience, skip checks entirely.

## Handoff to pair

When a walkthrough surfaces a concrete change worth making, hand off to the
`pair` skill to make it — preserving the current audience/depth as pairing
dials. Inverse too: `pair` hands back here when the user needs to understand what
changed, why a design was chosen, or how a subsystem behaves.

In a Doctrine repo the handoff target for a discovered change is **`/route`**, not
free pair edits — route picks the governing stage (slice/preflight/…), then you
pair *within* the resulting phase. A walkthrough must not become a governance bypass.

## In a Doctrine repo (optional)

Portable; ignore elsewhere. Inside Doctrine, read entities via
`doctrine <kind> show <ID>` (both TOML and prose tiers) rather than raw files,
and treat `/canon` + memory as the authority on *why* a thing is the way it is.
Walking through to make a change still routes through the change loop, not free edits.
