/code-walkthrough

name: code-walkthrough
description: >
  Walks a person through code changes one step at a time in conversation, starting at the entry point and following the
  flow that changes, showing a small chunk per step and explaining it in plain language. Defaults to the current
  branch's changes, and walks the code from the perspective of any context provided instead — a file, directory,
  symbol, pull request, plan, or ticket. Use when someone wants to be walked through, taught, paced through, or shown
  around code or a branch step by step, or to learn how a change works before reviewing or extending it. Stops after
  every step and waits, so the learner sets the pace. Paces through code that already exists and builds nothing — to
  build new work while being paced through it, use pairing. Does not produce a written overview to read alone — use
  code-overview. Does not review code quality — use code-review. Does not diagnose bugs — use investigate.
arguments: size
argument-hint:
  "[size: small | medium | large | dynamic] [target: a file, directory, symbol, PR reference, or plan — defaults to the
  current branch's changes]"
allowed-tools:
  Read, Glob, Grep, Agent, Bash(git *), Bash(gh *), Bash(find *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• git installed: !`which git 2>/dev/null || echo "not installed"`
• gh installed: !`which gh 2>/dev/null || echo "not installed"`
• current branch: !`git branch --show-current 2>/dev/null || echo "no git branch"`
• default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`
• repository root: !`git rev-parse --show-toplevel 2>/dev/null || pwd`
• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

Read these before doing anything. They constrain every step below.

• **One step per turn, then stop and wait.** Present exactly one walkthrough step, then end the turn. Never chain two

steps together, never run ahead to finish the itinerary, and never treat a short acknowledgement as permission to batch. BECAUSE the pacing _is_ the deliverable: a learner who receives six steps at once is reading a document, which is `code-overview`'s job, and the understanding this skill exists to build comes from stopping long enough to ask a question. The single exception is an explicit request for more than one step ("show me the rest", "give me the next three"), which you honor as asked.

• **A question holds your place; it never advances it.** When the learner asks about the step just presented instead of

moving on, answer at the same plain-language level, then re-offer the same next step. The step counter does not move. BECAUSE the question is the learning happening, and advancing past it silently abandons the reason they asked.

• **Every step names the full path from the repository root.** Each step's heading carries the complete

repository-root-relative path (`han-coding/skills/code-review/SKILL.md`), never a bare filename (`SKILL.md`) and never a path fragment. BECAUSE a bare filename is unsearchable and ambiguous in any repository with a `SKILL.md`, an `index.ts`, or a `README.md` in more than one directory, and the learner's next move is reliably to open the file themselves.

• **Small chunks, always.** Each step shows a few lines up to roughly thirty — the smallest excerpt that carries the

point — never a whole file and never an entire diff hunk pasted for completeness. BECAUSE the excerpt is an illustration of the sentence you just wrote, not the evidence for it; a wall of code moves the reading work back onto the person the walkthrough is supposed to be teaching.

• **Plain language, and the why before the what.** Explain each step as a problem being solved or a goal being served,

then what the code does about it. Keep the explanation to a short paragraph a person could read aloud. Source the standard by invoking `han-communication:explanation-guidance` (Step 3) and hold it for every turn of the session.

• **Follow the flow, then name the rest.** The itinerary follows the execution path from the entry point through the

change. Files off that path — tests, docs, index entries, config, mechanical renames — are named together in the closing step with one line each on why they changed. BECAUSE a flow the learner can follow is worth more than file-by-file completeness, and silently dropping a changed migration or test file is the gap that bites them later.

• **Teaching, never judging.** The walkthrough raises no findings, no severities, and no recommended changes, and it

never grades the code it is explaining. BECAUSE judging the change is `code-review`'s job, and a learner who cannot yet follow the flow has no basis to evaluate a critique of it. Saying "this is the part people find confusing" as navigation is fine; saying "this should have been extracted" is not.

• **Accurate to the code, always.** Every claim — the entry point, the order of the flow, what each chunk does, why it

changed — must be grounded in code you actually read. Never infer a step you did not verify, and never invent a rationale the evidence does not support; where the why is inferred rather than stated anywhere,