code-walkthrough

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, 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, say it is inferred. BECAUSE a confidently wrong walkthrough builds a mental model the learner will trust and act on for months.
• Read-only, and writes nothing. The skill explains; it never edits the target and never writes a file. The conversation is the whole deliverable. BECAUSE a durable written artifact is code-overview's output, and the absence of one here is what keeps the two skills distinct.
• Default to small. Start size classification at small and escalate only on a clear signal. BECAUSE under-dispatching is recoverable by exploring more mid-walk, while over-dispatching burns the context this session needs to survive across many turns.
• The step format lives at references/walkthrough-step-format.md. Render that format; do not invent a structure inline.