# Walkthrough > 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. - Skill: `davidlee/walkthrough` (Agent Skill) - Install (CLI): `npx skillmds@latest add davidlee/walkthrough` - Raw SKILL.md: https://api.skillmd.com/api/skills/davidlee/walkthrough/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: davidlee (https://skillmd.com/u/davidlee) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/davidlee/walkthrough --- # 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. Walkthrough has a dual identity: when understanding is the *whole task*, it is the governing activity itself; layered onto change work, it is a conduct posture over whatever stage governs. Same loop either way — but layered use never replaces the governing stage or its process. ## Dials Set by the user, else inferred, else defaults: ``` /walkthrough audience=expert depth=deep ``` - **audience** — `expert` · `mixed` (default) · `learner` — the governing 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. Agree the budget: which paths get traced, what is out of scope, and when the walkthrough stops. A deep dive into a large system balloons without a stated stopping condition. 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. Then route what must outlive the session: changes worth making re-enter the change loop (below); everything else harvests per `harvest.md`. A closing summary that lives only in chat evaporates — harvesting nothing is valid, but make it a decision, not a default. ## 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 show ` (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. Harvest per `harvest.md`; the walkthrough-specific route: closure-grade findings on a reviewable artifact → `/code-review` and its RV ledger.