From 21d0c6cc72eda23a167dfd4b7557b70bf4aed179 Mon Sep 17 00:00:00 2001 From: River Lynn Bailey Date: Mon, 10 Aug 2026 08:54:47 -0600 Subject: [PATCH 1/5] feat(han-coding): add the code-walkthrough skill Paces a person through code changes one step at a time in conversation, starting at the entry point and following the flow that changes. Each step names the full repository-root-relative path, shows a small excerpt, explains it in plain language, then stops and waits. Defaults to the current branch's changes, and walks from the perspective of any provided context instead. Files off the execution path are named together in the closing step so nothing is dropped. Also points code-overview and code-review back at the new skill, so disambiguation works in both directions. --- han-coding/skills/code-overview/SKILL.md | 3 +- han-coding/skills/code-review/SKILL.md | 3 +- han-coding/skills/code-walkthrough/SKILL.md | 233 ++++++++++++++++++ .../references/walkthrough-step-format.md | 91 +++++++ 4 files changed, 328 insertions(+), 2 deletions(-) create mode 100644 han-coding/skills/code-walkthrough/SKILL.md create mode 100644 han-coding/skills/code-walkthrough/references/walkthrough-step-format.md diff --git a/han-coding/skills/code-overview/SKILL.md b/han-coding/skills/code-overview/SKILL.md index 5ab2ecc..a7b5885 100644 --- a/han-coding/skills/code-overview/SKILL.md +++ b/han-coding/skills/code-overview/SKILL.md @@ -8,7 +8,8 @@ description: > symbol, or a PR's changes. Writes the overview to a scratch file and changes no code. Does not review code quality or raise findings — use code-review for auditing changes or post-code-review-to-pr for posting them. Does not produce durable feature or system documentation — use project-documentation. Does not assess architecture or structural risk — - use architectural-analysis. Does not diagnose bugs or root-cause failures — use investigate. + use architectural-analysis. Does not diagnose bugs or root-cause failures — use investigate. Does not pace a person + through the code one step at a time in conversation — use code-walkthrough. arguments: size argument-hint: "[size: small | medium | large | dynamic] [target: file, directory, symbol, or PR reference — defaults to the current branch's diff --git a/han-coding/skills/code-review/SKILL.md b/han-coding/skills/code-review/SKILL.md index 1007f12..7b2795d 100644 --- a/han-coding/skills/code-review/SKILL.md +++ b/han-coding/skills/code-review/SKILL.md @@ -5,7 +5,8 @@ description: evaluate, or check code, even if they never use the word "review." Does not post comments to GitHub pull requests — use post-code-review-to-pr for that. Does not analyze architectural structure or module boundaries — use architectural-analysis for that. Does not explain code or a PR to build understanding before reviewing — use - code-overview for that. Does not capture feedback on Han''s own skills — use han-feedback for that.' + code-overview for a written overview, or code-walkthrough to be paced through it one step at a time. Does not capture + feedback on Han''s own skills — use han-feedback for that.' arguments: size argument-hint: "[size: small | medium | large | dynamic] [optional context about changes or areas to focus on]" allowed-tools: Bash(git *), Bash(gh *), Bash(make *), Bash(npm *), Read, Write, Grep, Glob, Agent diff --git a/han-coding/skills/code-walkthrough/SKILL.md b/han-coding/skills/code-walkthrough/SKILL.md new file mode 100644 index 0000000..fa8fa66 --- /dev/null +++ b/han-coding/skills/code-walkthrough/SKILL.md @@ -0,0 +1,233 @@ +--- +name: code-walkthrough +description: > + Walks a person through a set of code changes one step at a time in conversation, starting at the entry point and + following the flow that changes, showing a small chunk of code per step and explaining it in plain language so they + learn what it does and why. 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 and can ask questions + as they go. Writes no files and changes no code. Does not produce a written overview document to read alone — use + code-overview. Does not review code quality or raise findings — use code-review. Does not diagnose bugs or root-cause + failures — 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 *) +--- + +## 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: !`echo "${CLAUDE_CONFIG_DIR:-$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, 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](./references/walkthrough-step-format.md).** Render + that format; do not invent a structure inline. + +# Walk Someone Through Code + +## Step 1: Resolve the Scope + +**Bind `$size`.** If the first positional argument is `small`, `medium`, `large`, or `dynamic`, bind `$size` to it. +Anything else is part of the target, not a size; bind `$size` to the literal `none provided`. + +**Note tool availability.** Read `git installed` and `gh installed` from Project Context. If `git installed` is empty or +reads `not installed`, git is unavailable — see the degraded paths below. + +**Resolve the target by this fixed precedence**, so an ambiguous string never silently selects the wrong scope: + +1. **No target given** → the current branch's changes against the default branch. This is the default and the most + common invocation. It needs git, not a remote pull request. +2. **A pull request reference or URL** (`#82`, `https://github.com/owner/repo/pull/82`) → that pull request's changes. + Requires `gh`. +3. **An existing file or directory path** (confirm it resolves with Glob or find) → that code, walked as it stands + rather than as a change. +4. **A symbol** (a function, class, type, or other named entity) → that symbol, resolved with Grep across the + repository. +5. **Any other context** — a plan file, a ticket, a described capability, a conversation above — → walk the code from + that context's perspective, covering the code that context concerns and ordering the walk by what that context cares + about. + +**Handle the unresolvable and empty cases** (state the problem plainly and stop; never guess): + +- No target given and the working tree is clean with no branch changes → say the branch has no changes to walk and ask + for a target. +- No target given and git is unavailable → say the branch default needs git, and ask for a file, directory, or symbol, + which still works without it. +- A pull request reference with `gh` unavailable or unreachable → say so and offer a local target instead. +- A path or symbol that resolves to nothing, or a symbol ambiguous across several definitions → report exactly what + could not be resolved and ask the learner to disambiguate. + +**Resolve project context.** If `CLAUDE.md` is present, read its `## Project Discovery` section for conventions; fall +back to `project-discovery.md`. These settle language and framework questions so the explorers infer less. If neither +exists, note that surrounding-code inference applies and pass that into the briefs. + +## Step 2: Classify Size and Trace the Flow + +**Classify the target's size. Default to small**, and stay at the smaller band when a signal is borderline. + +- **Small** _(default)_ — one file, one symbol, or a change touching a few files in one subsystem. +- **Medium** — a directory or module, or a change across one or two adjacent subsystems. +- **Large** — several subsystems, or a change spanning many files across them. + +**Apply the size override.** If `$size` is not `none provided`, use it: a band value is the band and skips the +signal-based classification, while `dynamic` forces the signal-based classification even when the project config sets a +default band. If `$size` is `none provided` and the project config supplies a band via `default-swarm-size` (per +[../../references/config-rule.md](../../references/config-rule.md)), use that band and name the config as the source in +Step 3's announcement. A conversational override ("walk me through it in detail") is equivalent. + +**Gather the input.** For a branch or pull request, capture the change set and its intent: + +- **Current branch**: determine the default branch from Project Context (`default branch`), falling back to `main` or + `master`. Capture `git diff {default-branch}...HEAD` for committed work, then `git diff` and `git diff --cached` for + uncommitted work, each as its own Bash command so a large diff streams incrementally. Capture + `git log {default-branch}..HEAD --pretty=format:%B` for intent. When `gh` is available, also run + `gh pr view --json title,body` to pick up the change's stated purpose; if no pull request exists for the branch, skip + this without failing. +- **A named pull request**: run `gh pr view {ref} --json title,body` for intent and `gh pr diff {ref}` for the change + set. +- **A file, directory, symbol, or other context**: read the target and enough of its neighbors to know its boundary — + what it imports and what imports it. + +**Dispatch `han-core:codebase-explorer` to trace the flow.** Scale the count to the band and launch every agent in a +single message so they run concurrently: + +- **Small** — one explorer over the target or the changed files. +- **Medium** — two or three explorers, each over a coherent slice. +- **Large** — three to five explorers, each scoped to one subsystem or one area of the change. + +Each brief must contain the resolved target (and, for a change, the changed-file set and the captured intent), the +project conventions from Step 1 or a note that surrounding-code inference applies, and the instruction to report **where +the flow starts and the order it runs in** — the entry point a request, command, or event actually arrives at, each +subsequent hop, and which changed files sit on that path versus off it — as concrete findings citing +**repository-root-relative paths**. Instruct each explorer to report what it found and **not to assess quality**, and to +say so plainly where the entry point or the why is not recoverable rather than inferring one. + +Wait for the whole wave before building the itinerary. Dispatching to trace the flow rather than reading everything +inline keeps the main context lean, which matters here BECAUSE this session runs across many turns and a context +exhausted at step 2 cannot finish the walk. + +## Step 3: Build the Itinerary and Announce It + +Invoke `han-communication:explanation-guidance` to surface Han's standard for explaining technical work to a reader who +will not implement it. It runs inline and hands control straight back. That standard governs every turn of this session, +BECAUSE every turn goes to a person who is trying to learn the code rather than write it. + +**Order the itinerary by the flow, starting at the entry point.** Read +[references/walkthrough-step-format.md](./references/walkthrough-step-format.md) and apply its ordering rules. Each step +is one stop on the execution path, identified by its full repository-root-relative path and the one idea it teaches. +Bound the length to the band: roughly three to five steps at small, five to eight at medium, and eight to twelve at +large. Where the flow is longer than the band allows, keep the stops where the change's behavior actually turns and fold +the pass-through hops into the neighboring step. + +**Reserve the closing step for everything off the flow** — tests, documentation, index entries, configuration, +mechanical renames — with one line each on why it changed. Every changed file lands either on the flow or in that +closing step; none is dropped. + +**Announce the walk in one short turn, then present step 1 in that same turn.** The announcement states what is being +walked, the size band and why, and the number of steps ahead — for example, +`Walking the current branch, size medium: 6 steps following a review request from the slash command through agent +dispatch.` Name tool degradation in the same line when it applies, and name the config when it supplied the band. Do NOT +stop for approval here: this skill is read-only and re-runnable, so a gate on a reversible operation only trains the +learner to approve without reading. Honor any adjustment they make. + +## Step 4: Walk One Step Per Turn + +This is the loop the whole skill exists for. Repeat it until the itinerary is done. + +1. **Present exactly one step**, rendered per + [references/walkthrough-step-format.md](./references/walkthrough-step-format.md): the position and the full + repository-root-relative path, a short plain-language explanation leading with why, a small code or diff excerpt, and + a one-line handoff naming what the next step covers and inviting a question. +2. **End the turn.** Wait for the learner. Do not continue, do not summarize what is coming, and do not present the next + step in the same turn. +3. **Read what comes back and route it:** + - An advance (`next`, `continue`, `go on`) → present the next step. + - A request to go deeper → read more of the current file or its neighbors and expand on the current step, still as + one step, then re-offer the next one. + - A request to skip, jump to a named file, or go back → move the position there, say in one line where you moved to, + and continue from there. + - A request for several steps or the rest of the walk → honor it as asked; this is the one case where more than one + step goes out in a turn. + - A request to stop → stop, and say where in the itinerary they stopped so they can resume later. + - **Anything else is a question, and a question never advances the walk.** Answer it at the same plain-language + level, then re-offer the same next step with the counter unmoved. This is the case to get right: the instinct is to + answer and roll straight into the next step, which silently spends the stop the learner just used to ask. +4. **Revise the itinerary when the code contradicts it.** If tracing reveals the flow goes somewhere the plan did not + predict, change the remaining steps, say so in one line, and carry on. NEVER walk a step you now know is wrong just + because it was in the plan. + +If a step's file cannot be read or a symbol no longer resolves, say exactly what failed, skip that step, and continue +the walk. NEVER abandon the session over one unreadable file, BECAUSE the learner keeps the value of every step already +walked and every step still ahead. + +## Step 5: Close the Walk + +After the last flow step, present the closing turn: + +1. **The off-flow changes**, as the itinerary reserved them: each remaining changed file by its full + repository-root-relative path, with one line on why it changed. Omit this entirely when the walk was not of a change + set, or when every changed file sat on the flow. +2. **A short recap** — three or four plain sentences tying the steps back together into what the change does and why it + exists. Carry no file paths, no type names, and no symbol names in these sentences, and write them under the + explanation standard sourced in Step 3, BECAUSE the learner's reliable next move is to repeat this summary to someone + else in their own words. +3. **One line on where to go next**, naming the sibling skill that fits what they said they wanted the understanding + for: `code-review` to audit the change, `code-overview` for a written document they can keep or share, `investigate` + to chase a bug they spotted. Recommend nothing about the code itself. diff --git a/han-coding/skills/code-walkthrough/references/walkthrough-step-format.md b/han-coding/skills/code-walkthrough/references/walkthrough-step-format.md new file mode 100644 index 0000000..32570a6 --- /dev/null +++ b/han-coding/skills/code-walkthrough/references/walkthrough-step-format.md @@ -0,0 +1,91 @@ +# Walkthrough Step Format + +This file carries two things the walkthrough needs: how to order the itinerary, and how to render a single step. The +skill's `SKILL.md` owns the process; this file owns the shape of what the learner sees. + +## Ordering the Itinerary + +Order stops by the path the code actually executes, not by the order files appear in a diff, not alphabetically, and not +by layer. + +1. **Start where control enters.** The entry point is where a request, command, event, or user action first reaches the + changed code — a route handler, a CLI command, a message consumer, an exported function another package calls, a + slash command's first instruction. When a change has no runtime entry point (a pure data or configuration change), + start at the thing that reads it. +2. **Follow one hop per step.** Each subsequent step is the next place control or data goes. A step earns its place when + the behavior turns there: a branch, a transformation, a dispatch, a boundary crossing, a persisted write. +3. **Fold pass-through hops into their neighbors.** A file that only forwards a call to the next one is not a stop; name + it inside the step it forwards into. +4. **Keep each step to one idea.** If a step needs two paragraphs to explain because two unrelated things changed in one + file, split it into two steps against the same file. +5. **Put the off-flow files in the closing step.** Tests, documentation, index entries, configuration, lockfiles, and + mechanical renames get one line each at the end, never a step of their own. + +When two changed files sit at the same depth with no ordering between them, walk the one whose behavior the other +depends on first. + +## Anatomy of One Step + +Every step renders these four parts, in this order. + +### 1. The heading: position and full path + +```markdown +### Step 2 of 6 — `han-coding/skills/code-review/SKILL.md` +``` + +The path is always **repository-root-relative and complete**. Never a bare filename, never a fragment, never a path +relative to some other directory. A learner reading `SKILL.md` cannot find the file; a learner reading +`han-coding/skills/code-review/SKILL.md` can open it in one move. + +When a step targets a specific symbol, name it after the path: `` `src/billing/invoice.ts` — `applyProration()` ``. + +### 2. The explanation: why first, then what + +A short paragraph — usually two to four sentences — that leads with the problem being solved or the goal being served, +then says what the code does about it. Written for someone who did not do this work and does not yet know the codebase. + +Say what changed in terms of behavior a person could observe, not in terms of the mechanism. Where an outside +technology, a runtime, or a term coined inside this codebase has to appear, explain it in half a sentence at first use. + +### 3. The excerpt: the smallest chunk that carries the point + +A few lines up to roughly thirty. For a change, prefer a diff excerpt so the before and after are both visible. For +existing code, a plain fenced excerpt. + +Trim aggressively. Cut imports, boilerplate, unrelated lines, and untouched context that does not help. Replace elided +regions with a comment marker rather than pasting them. The excerpt illustrates the sentence above it; it is not the +evidence for it. + +### 4. The handoff: one line naming what is next + +One line that says what the next step covers, then invites either an advance or a question. It ends the turn. + +## Worked Example + +````markdown +### Step 2 of 6 — `han-coding/skills/code-review/SKILL.md` + +A review used to pick its specialists from the file types in the diff, so a change to a retry loop got a style +reviewer and nobody who thinks about what happens when the retry never succeeds. This step is where that choice is +made, and it now reads what the code does rather than what kind of file it lives in. + +```diff +- Select agents by the file extensions present in the diff. ++ Select agents by what the changed code does. When the diff touches ++ a retry, timeout, or queue path, dispatch han-core:on-call-engineer. +``` + +Next: where that dispatch list is actually built and handed to the agents. Say **next**, or ask me anything about this +step. +```` + +## What a Step Never Does + +- **Never judges the code.** No findings, no severities, no "this should have been extracted". Navigational notes are + fine: "this is the part that is hard to follow, and here is why" teaches; "this is badly factored" grades. +- **Never states diff statistics.** No lines changed, files changed, or commit counts. They go stale immediately and + teach nothing. +- **Never pastes a whole file.** If a step seems to need one, the step is really two or three steps. +- **Never claims a flow it did not read.** An unverified hop is an invented one. Where the order or the reason is + inferred rather than found in the code, its commits, or its tests, say that it is inferred. From bd19658b3fa851aa9ed79152ca4e4a6771672176 Mon Sep 17 00:00:00 2001 From: River Lynn Bailey Date: Mon, 10 Aug 2026 08:57:51 -0600 Subject: [PATCH 2/5] docs(han-coding): document code-walkthrough and index it Adds the long-form operator doc and wires the skill into every surface the repo conventions require complete: the han-coding README scent line, the alphabetized skills index, the plugin.json skill list, the root project map, and the workflows composition map. The workflows entry states the choice between the two understanding skills: code-walkthrough when you want to be taught step by step, code-overview when you want one artifact to keep or share. No version bump. --- CLAUDE.md | 3 +- docs/skills/README.md | 2 + docs/workflows.md | 4 + han-coding/.claude-plugin/plugin.json | 2 +- han-coding/README.md | 2 + han-coding/docs/skills/code-walkthrough.md | 147 +++++++++++++++++++++ 6 files changed, 158 insertions(+), 2 deletions(-) create mode 100644 han-coding/docs/skills/code-walkthrough.md diff --git a/CLAUDE.md b/CLAUDE.md index 0144cde..6e25b9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,7 +22,8 @@ depends on `han-communication` and `han-core` and is bundled by the `han` meta-p `han-coding` (the coding skills you reach for while working in code: writing it with `tdd` and `refactor`, designing an interface contract with `design-an-api`, plus reviewing, overviewing, analyzing, -testing, investigating, and standardizing it with `code-review`, `code-overview`, `architectural-analysis`, +testing, investigating, and standardizing it with `code-review`, `code-overview`, `code-walkthrough`, +`architectural-analysis`, `automated-test-planning`, `manual-test-planning`, `investigate`, and `coding-standard`; depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin), `han-github` (GitHub-facing skills), `han-reporting` (reporting and summary skills; depends only on diff --git a/docs/skills/README.md b/docs/skills/README.md index 9eab034..ae0ea22 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -29,6 +29,8 @@ skill-and-agent split is fuzzy, read [Concepts](../concepts.md) first. (changing no code), show it for review, then publish it as one Confluence page after confirmation. - [`/code-review`](../../han-coding/docs/skills/code-review.md) — Run a comprehensive code review on the current branch or specified files, with a size-scaled roster of specialist agents. +- [`/code-walkthrough`](../../han-coding/docs/skills/code-walkthrough.md) — Walk someone through a branch's changes one + step at a time in conversation, from the entry point along the flow, stopping after every step so they set the pace. - [`/coding-standard`](../../han-coding/docs/skills/coding-standard.md) — Create and update coding standards from existing patterns or evidence-based research. - [`/design-an-api`](../../han-coding/docs/skills/design-an-api.md) — Design the contract for an API change inside one diff --git a/docs/workflows.md b/docs/workflows.md index 2ba8441..c4174d5 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -137,6 +137,10 @@ These chains are linear, so they need no diagram. - **[`/code-overview`](../han-coding/docs/skills/code-overview.md) → [`/code-review`](../han-coding/docs/skills/code-review.md).** Get oriented in unfamiliar code or a PR first, then judge whether it is any good. +- **[`/code-walkthrough`](../han-coding/docs/skills/code-walkthrough.md) → + [`/code-review`](../han-coding/docs/skills/code-review.md).** The same chain when you want to be taught rather than + handed a document: walk the change one step at a time, asking questions as you go, then review it. Reach for + `/code-overview` instead when you want one artifact you can keep, share, or paste into a PR description. - **[`/project-documentation`](../han-documentation/docs/skills/project-documentation.md) → the specialized documents.** Feature and system docs live in `/project-documentation`, but three kinds of writing route elsewhere: a decision and its rejected alternatives go to diff --git a/han-coding/.claude-plugin/plugin.json b/han-coding/.claude-plugin/plugin.json index 6875f92..3632c08 100644 --- a/han-coding/.claude-plugin/plugin.json +++ b/han-coding/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "han-coding", - "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, plus design-an-api (designing an interface contract for one stated goal through an options round, a question round, and an adversarial validation round), code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.", + "description": "Coding-facing skills for the Han suite: writing, reviewing, testing, investigating, and standardizing code. Home of the tdd skill, which drives a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate, and the refactor skill, which restructures existing code without changing its behavior through a test-gated refactoring loop, plus design-an-api (designing an interface contract for one stated goal through an options round, a question round, and an adversarial validation round), code-review (comprehensive review of local changes), code-overview (a progressive-disclosure, understand-now overview of unfamiliar code or a PR's changes), code-walkthrough (a paced, one-step-at-a-time walk through a branch's changes in conversation), architectural-analysis (module-level coupling, data flow, concurrency, risk, and SOLID assessment), automated-test-planning (coverage-gap and edge-case test plans), manual-test-planning (plain-language manual test plans a person runs by hand), investigate (evidence-based root-cause debugging), and coding-standard (creating and updating coding standards). Depends on han-core and han-communication; bundled by the han meta-plugin.", "version": "3.0.0", "dependencies": ["han-communication", "han-core"] } diff --git a/han-coding/README.md b/han-coding/README.md index c719c66..2a4395a 100644 --- a/han-coding/README.md +++ b/han-coding/README.md @@ -19,6 +19,8 @@ specialist agents to cover each dimension in parallel. Reach for it once there i files, with a size-scaled roster of specialist agents. - [`/code-overview`](docs/skills/code-overview.md) — Produce a human-readable, progressive-disclosure overview of unfamiliar code or a PR's changes, leading with why the code exists; raises no findings. +- [`/code-walkthrough`](docs/skills/code-walkthrough.md) — Walk someone through a branch's changes one step at a time in + conversation, from the entry point along the flow, stopping after every step so they set the pace. - [`/architectural-analysis`](docs/skills/architectural-analysis.md) — Assess a module's coupling, data flow, concurrency, risk, and SOLID alignment through a spine of structural, behavioral, risk, and architecture agents. - [`/automated-test-planning`](docs/skills/automated-test-planning.md) — Produce a prioritized test plan for a branch or directory. diff --git a/han-coding/docs/skills/code-walkthrough.md b/han-coding/docs/skills/code-walkthrough.md new file mode 100644 index 0000000..83383c5 --- /dev/null +++ b/han-coding/docs/skills/code-walkthrough.md @@ -0,0 +1,147 @@ +# /code-walkthrough + +Operator documentation for the `/code-walkthrough` skill in the han plugin. This document helps you decide _when_ and +_how_ to use the skill. For what the skill does internally, read the skill definition at +[`han-coding/skills/code-walkthrough/SKILL.md`](../../skills/code-walkthrough/SKILL.md). + +> See also: [Plugin README](../../README.md) · [Repo root](../../../README.md) · [All skills](../../../docs/skills/README.md) · +> [All agents](../../../docs/agents/README.md) · [Sizing](../../../docs/sizing.md) + +## TL;DR + +- **What it does.** Walks you through a set of code changes one step at a time in conversation, starting at the entry + point and following the flow that changes, showing a small excerpt per step and explaining it in plain language. +- **When to use it.** You want to learn what a branch does and why, and you want to be paced through it rather than + handed a document. +- **What you get back.** The conversation itself. The skill writes no file and changes no code. + +## Key concepts + +- **One step per turn.** The skill presents a single step, then stops and waits for you. It never chains steps or runs + ahead to finish. The stopping is the point: it is the space where you ask the question that turns reading into + understanding. +- **A question holds your place.** Ask about the step you just saw and the skill answers at the same plain-language + level, then re-offers the same next step. The counter does not move. You can interrupt as often as you like without + losing your position. +- **Full paths, every step.** Every step heading carries the complete repository-root-relative path + (`han-coding/skills/code-review/SKILL.md`), never a bare filename. You can open the file in one move, and you can + search for it later. +- **Flow order, not diff order.** The itinerary starts where control enters the changed code and follows one hop per + step. It is not alphabetical, not the order files appear in the diff, and not grouped by layer. +- **Nothing is silently dropped.** Files off the execution path — tests, docs, index entries, config, mechanical + renames — are named together in the closing step with one line each on why they changed. +- **Teaching, never judging.** The walkthrough raises no findings, no severities, and no recommended changes. "This is + the part people find confusing" is navigation and is welcome; "this should have been extracted" is a review, and that + is `/code-review`'s job. +- **Size-aware.** The skill classifies the target as small / medium / large, defaults to small, and scales how many + `codebase-explorer` agents it dispatches to trace the flow. See [Sizing](../../../docs/sizing.md). + +## When to use it + +**Invoke when:** + +- You are picking up a branch someone else wrote and want to learn what it does before you touch it. +- You wrote the branch a while ago and need to rebuild your own mental model of it. +- You are onboarding onto an unfamiliar flow and want to be walked from the entry point through to the end. +- You want to understand a change well enough to explain it to someone else. + +**Do not invoke for:** + +- **A written overview you can keep, share, or paste.** Use [`/code-overview`](./code-overview.md) instead. It produces + one document; this skill produces a paced conversation. +- **Judging whether the code is any good.** Use [`/code-review`](./code-review.md) instead (or + [`/post-code-review-to-pr`](../../../han-github/docs/skills/post-code-review-to-pr.md) to post a review to GitHub). +- **Diagnosing a bug or root-causing a failure.** Use [`/investigate`](./investigate.md) instead. +- **Assessing architecture, coupling, or structural risk.** Use [`/architectural-analysis`](./architectural-analysis.md) + instead. + +## How to invoke it + +Run `/code-walkthrough` in Claude Code. + +Give it: + +1. **A target (optional).** With nothing, the skill walks the current branch's changes against the default branch. That + is the common case. You can also name a file, a directory, a symbol, a pull request reference or URL, or a plan or + ticket, in which case the skill walks the code from that context's perspective and orders the walk by what that + context cares about. +2. **A size (optional).** `small`, `medium`, `large`, or `dynamic` as the first positional argument, when you want to + override the skill's auto-classification. Size sets both the exploration roster and roughly how many steps the walk + runs. + +Example prompts: + +- `/code-walkthrough`. _"Walk me through the changes on this branch, one step at a time."_ +- `/code-walkthrough #82`. _"Teach me what pull request 82 does before I review it."_ +- `/code-walkthrough src/billing/`. _"Show me around the billing module."_ +- `/code-walkthrough large`. _"Walk me through this branch in detail; it spans several subsystems."_ + +Once the walk starts, you drive it. Say `next` to advance. Ask a question to stay put. Say "go deeper" to expand the +current step, name a file to jump there, or say "stop" to end the walk and be told where you left off. + +## What you get back + +A conversation, not a file. The skill opens with a one-line announcement naming what it is walking, the size band and +why, and how many steps lie ahead, then presents step 1 in that same turn. There is no approval gate before it starts, +because the skill is read-only and re-runnable, and a gate on a reversible operation only teaches you to approve without +reading. + +Each step carries four parts: + +1. **A heading** with your position in the walk and the full repository-root-relative path, plus the symbol name when + the step targets one. +2. **A short explanation** — two to four sentences leading with the problem being solved, then what the code does about + it, written for someone who did not do the work. +3. **A small excerpt** — a few lines up to roughly thirty, trimmed of imports and boilerplate. A diff excerpt for a + change, so before and after are both visible; a plain fenced excerpt for existing code. +4. **A one-line handoff** naming what the next step covers, then the turn ends. + +The walk closes with the off-flow changed files (each by full path, one line each on why it changed), a three-or-four +sentence recap carrying no file paths or symbol names, and one line pointing at whichever sibling skill fits what you +said you wanted the understanding for. + +If the code turns out to contradict the itinerary mid-walk, the skill revises the remaining steps, says so in one line, +and carries on rather than walking a step it now knows is wrong. If one file cannot be read, it says what failed, skips +that step, and continues. + +## How to get the most out of it + +- **Ask the question when it lands.** The pause after each step exists for exactly this. A walkthrough you interrupt + four times teaches more than one you click through. +- **Say "go deeper" instead of re-running.** Expanding the current step is cheaper and keeps your place. +- **Let the bare invocation carry the branch case.** On a feature branch, `/code-walkthrough` with no argument is + already pointed at what you want. +- **Pair it with `/code-review` next.** The walkthrough teaches you how the change works; the review tells you whether + it is any good. Understanding first, judgment second. + +## Sizing + +| Size | Typical target | Explorers | Steps | +| --------------------- | --------------------------------------------------------------- | --------- | ----- | +| **Small** _(default)_ | One file, one symbol, or a change across a few files | 1 | 3–5 | +| **Medium** | A directory or module, or a change across one or two subsystems | 2–3 | 5–8 | +| **Large** | Several subsystems, or a change spanning many files across them | 3–5 | 8–12 | + +Classification defaults to small and stays at the smaller band when a signal is borderline. Where the real flow runs +longer than the band allows, the skill keeps the stops where behavior actually turns and folds pass-through hops into +their neighbors. See [Sizing](../../../docs/sizing.md) for the cross-skill model. + +## Cost and latency + +The skill runs on the default model tier. The one expensive step is the parallel `han-core:codebase-explorer` wave in +Step 2, which traces the flow before the walk begins; everything after that is conversation. Tracing is dispatched +rather than done inline specifically because this session runs across many turns, and a context exhausted at step 2 +cannot finish the walk. There is no synthesis pass, no validation roster, and no output file, so a small walkthrough is +cheap and safe to run often. + +## Related documentation + +- [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. +- [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs + tree. +- [`code-overview`](./code-overview.md). The written-document counterpart. Same understanding goal, one artifact + instead of a paced conversation. +- [`code-review`](./code-review.md). What you run after the walkthrough, when you are ready to judge rather than learn. +- [`codebase-explorer`](../../../han-core/docs/agents/codebase-explorer.md). Traces the flow and entry points the + itinerary is built from. +- [Sizing](../../../docs/sizing.md). The cross-skill small / medium / large model this skill classifies against. From 960a7dc74fce704186a64e33d9f07e7d09a3a2b9 Mon Sep 17 00:00:00 2001 From: River Lynn Bailey Date: Mon, 10 Aug 2026 09:03:01 -0600 Subject: [PATCH 3/5] docs(how-to): add code-walkthrough to the understanding guide Phase 1 now presents two orientation moves rather than one. The overview hands you a map to keep; the walkthrough paces you through the flow and stops after each step. The guide picks between them by what you need next, not by depth. Ties the walkthrough to the guide's spine, the finding that verification is what separates finishing fast from understanding: the walkthrough gives you one full path and one small excerpt, then stops, which is the shape of a verification prompt already. Also renames the opening "walkthrough" to "guide" so the word no longer collides with the skill name, and rewords the code-overview PR example off "walk me through" for the same reason. --- docs/how-to/README.md | 2 +- ...lerate-understanding-of-unfamiliar-code.md | 95 ++++++++++++++----- 2 files changed, 71 insertions(+), 26 deletions(-) diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 9ef660a..4eb02df 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -27,7 +27,7 @@ doc tells you what the skill does; the how-to tells you how to run a workflow th - **[Accelerate your understanding of unfamiliar code](./accelerate-understanding-of-unfamiliar-code.md).** You have landed in code you do not know and want a fast mental model. Then you want a grounded, written artifact that you, your team, and Claude can all read again later, instead of re-deriving it every time. Covers `/code-overview`, - `/project-documentation`, and the Confluence wrappers that share the result. + `/code-walkthrough`, `/project-documentation`, and the Confluence wrappers that share the result. - **[Triage and investigate a bug](./triage-and-investigate-a-bug.md).** Something is broken or behaving oddly and you want a root cause backed by evidence, not a guess. Or the work is queued rather than immediate, and you want a structured triage document instead. diff --git a/docs/how-to/accelerate-understanding-of-unfamiliar-code.md b/docs/how-to/accelerate-understanding-of-unfamiliar-code.md index 940c832..564bf3b 100644 --- a/docs/how-to/accelerate-understanding-of-unfamiliar-code.md +++ b/docs/how-to/accelerate-understanding-of-unfamiliar-code.md @@ -1,8 +1,8 @@ # How To: Accelerate Your Understanding of Unfamiliar Code -A walkthrough for getting from "I have never seen this code before" to a mental model you can act on, fast. Then it -turns that model into a grounded, written artifact that you, your teammates, and Claude can all read again later, -instead of re-deriving it from scratch every time. +A guide for getting from "I have never seen this code before" to a mental model you can act on, fast. Then it turns +that model into a grounded, written artifact that you, your teammates, and Claude can all read again later, instead of +re-deriving it from scratch every time. > See also: [How-to index](./README.md) · [Quickstart](../quickstart.md) · [Skills](../skills/README.md) @@ -24,8 +24,8 @@ checked what the AI told them against the real source far more often. So the who orient you, then check it against the code," not "read the summary and move on." - You have a target you can name sharply. A file, a directory, a symbol, or a pull request. "The whole backend" is too - thin; `/code-overview` will ask you to narrow it. If you genuinely do not know where the feature lives yet, that is - fine: you start broad and drill in, but you still name the broad thing. + thin; both orientation skills will ask you to narrow it. If you genuinely do not know where the feature lives yet, + that is fine: you start broad and drill in, but you still name the broad thing. - You have the project checked out and, for the PR path, git available locally. The orientation step reads real source, so it needs the source. - You know roughly what you are trying to do with the code. Reviewing a PR, fixing a bug, extending a module, and @@ -36,9 +36,12 @@ orient you, then check it against the code," not "read the summary and move on." ## What you'll end up with -- A fast, throwaway orientation to the code, produced by [`/code-overview`](../../han-coding/docs/skills/code-overview.md): a - purpose statement, a Mermaid flow chart, the directly related context, and a where-to-start section, written to a - scratch file outside the repo. This is the "understand it now" artifact. +- A fast, throwaway orientation to the code, in one of two shapes. Run + [`/code-overview`](../../han-coding/docs/skills/code-overview.md) for a map you can keep: a purpose statement, a + Mermaid flow chart, the directly related context, and a where-to-start section, written to a scratch file outside the + repo. Run [`/code-walkthrough`](../../han-coding/docs/skills/code-walkthrough.md) instead for a paced tour: the same + understanding delivered one step at a time in the conversation, stopping after each step so you can ask. Either way + this is the "understand it now" artifact. - Optionally, a deeper read of the part that matters: a structural and risk assessment from [`/architectural-analysis`](../../han-coding/docs/skills/architectural-analysis.md) when you are about to change the code, or a root-caused investigation from [`/investigate`](../../han-coding/docs/skills/investigate.md) when something is broken. @@ -60,8 +63,14 @@ change the code or chase a bug. ### Phase 1: Get oriented fast -1. **Run [`/code-overview`](../../han-coding/docs/skills/code-overview.md) on your target.** This is the first thing you reach - for in unfamiliar code. Point it at a file, a directory, a symbol, or a PR. +Two skills orient you, and they differ in shape rather than depth. `/code-overview` hands you a finished map to read at +your own speed. `/code-walkthrough` takes you through the code one step at a time and stops after each one. Pick by what +you need next: a document you can keep and share, or a tour you can interrupt. + +Neither one raises findings about whether the code is any good. Both are orientation, not judgment. + +1. **Run [`/code-overview`](../../han-coding/docs/skills/code-overview.md) when you want a map you can keep.** Point it + at a file, a directory, a symbol, or a PR. > `/code-overview {path or symbol or PR}` @@ -69,7 +78,7 @@ change the code or chase a bug. > `/code-overview src/auth/` for _"help me understand the auth module before I work on it."_ - > `/code-overview #82` for _"walk me through pull request 82 so I know how to review it."_ + > `/code-overview #82` for _"explain pull request 82 so I know how to review it."_ > `/code-overview` with no argument on a feature branch, for _"explain what the changes on this branch do before I > review them."_ @@ -79,23 +88,49 @@ change the code or chase a bug. flow as a Mermaid chart, then the context and uses, then where to start. That ordering puts the most important understanding first, so if you stop reading after the purpose statement you are still oriented correctly. - The overview raises no findings about whether the code is any good; it is orientation, not judgment. + The skill writes the file to a scratch location outside the repo and shows you the path. Open it somewhere the + Mermaid charts render, or you lose the flow diagram to raw markup. + + Reach for this one when the understanding has an audience beyond you. The file is a thing you can paste into a PR + description or hand to a teammate. + +2. **Run [`/code-walkthrough`](../../han-coding/docs/skills/code-walkthrough.md) when you want to be taught the flow.** + It defaults to the current branch's changes, so on a feature branch you can invoke it bare. + + > `/code-walkthrough` for _"walk me through the changes on this branch, one step at a time."_ + + > `/code-walkthrough #82` for _"teach me what pull request 82 does before I review it."_ -2. **Open the overview where the charts render, and read it against the code.** The skill writes the file to a scratch - location outside the repo and shows you the path. Read it, but do not stop at reading. Open the entry points it names - in the where-to-start section and confirm they say what the overview says they say. This is the verification step the - research is emphatic about: the value comes from checking the explanation against the real source, not from consuming - it passively. The overview is grounded in actual files and real paths precisely so you can do this quickly. + > `/code-walkthrough src/billing/` for _"show me around the billing module."_ -3. **Re-run larger, or drill in, when coverage is partial.** If the target was bigger than the chosen size could cover, + The skill traces the flow with the same `codebase-explorer` agents, then walks it from the entry point. Each step + names one file by its full path from the repository root, shows a small excerpt, explains it in plain language, and + then stops. You say `next` to move on, ask a question to stay put, or say "go deeper" to expand where you are. + Changed files that sit off the execution path get named together at the end, so nothing goes missing quietly. + + Reach for this one when the understanding is for you and you learn by asking. There is no file at the end; the + conversation is the whole thing. + +3. **Check what you were told against the code.** This is the verification step the research is emphatic about, and it + is the step that separates finishing fast from understanding. After an overview, open the entry points named in the + where-to-start section and confirm they say what the overview says they say. During a walkthrough, open the file + named in the current step before you say `next`. + + The walkthrough is built to make this cheap. It gives you one full path and one small excerpt, then stops, which is + the shape of a verification prompt whether or not you treat it as one. Use the pause for that. + +4. **Re-run larger, or drill in, when coverage is partial.** If the target was bigger than the chosen size could cover, the overview adds a coverage note right after the header, naming what it skipped and the next size up. Re-run at the larger size for a fuller picture (`/code-overview large src/billing/`), or pick the one submodule that matters and run a focused small overview on that. Starting broad and narrowing is the normal motion when you did not know where the feature lived. + A walkthrough handles this differently. Rather than re-running it, say "go deeper" at the step that was too thin, + which expands that step and keeps your place in the walk. + At the end of Phase 1 you have a working mental model and a sense of where the important code is. For a quick review or -a small change, that may be all you need; skip to Phase 3 if you want to write it down, or stop here if the overview was -a one-time orientation. +a small change, that may be all you need; skip to Phase 3 if you want to write it down, or stop here if the orientation +was a one-time job. ### Phase 2: Go deeper where it matters @@ -175,6 +210,11 @@ can invent a different explanation each time. The defense is a grounded artifact `/code-review` to judge it. The overview orients you; the review evaluates the work. Do not use the overview as a review; it raises no findings on purpose. +- **You want to be taught the change, not handed a summary of it.** Run `/code-walkthrough` on the branch or the PR. + You get the same orientation paced one step at a time, and you can stop and ask at any step without losing your + place. This is the better fit when the code is unfamiliar enough that a finished document would leave you with + questions you cannot ask it. + - **The code is broken and that is why you are here.** Phase 1 still orients you fast, but the main event is `/investigate` from Phase 2, not `/project-documentation`. Document afterward only if the fix changed how the feature behaves. @@ -200,6 +240,9 @@ can invent a different explanation each time. The defense is a grounded artifact never committed or maintained; it is a point-in-time map. `/project-documentation` writes a maintained doc into the repo tree. Reach for the first to understand now and the second to remember later. Mixing them up is the most common mistake. +- **The walkthrough leaves nothing behind on purpose.** `/code-walkthrough` writes no file at all. That is the trade: + you get to ask questions as you go, and when the session ends the understanding lives only in your head. If you want + a record, run `/code-overview` on the same target afterward, or go to Phase 3 and write the durable doc. - **Everything is grounded in real source, so check it against real source.** Every skill in this guide reads actual files and cites real paths. That grounding exists so you can verify, which the research says is the step that turns reading into understanding. Open the files the artifacts name. @@ -207,20 +250,22 @@ can invent a different explanation each time. The defense is a grounded artifact is not decoration. In later sessions, when Claude explores the codebase, it reads that doc as project context. So the understanding you captured flows into every future planning, review, and overview pass without you doing anything else. -- **Sizing is read from the target, not the prompt length.** `/code-overview` and `/architectural-analysis` classify the - target and scale their agent rosters, defaulting to small and escalating only on a clear signal. Pass `small`, - `medium`, or `large` as the first argument when you already know the target is bigger than the default. See +- **Sizing is read from the target, not the prompt length.** `/code-overview`, `/code-walkthrough`, and + `/architectural-analysis` classify the target and scale their agent rosters, defaulting to small and escalating only + on a clear signal. Pass `small`, `medium`, or `large` as the first argument when you already know the target is bigger + than the default. For a walkthrough, the size also sets roughly how many steps the walk runs. See [Sizing](../sizing.md). ## Where to go next -- [`/code-review`](../../han-coding/docs/skills/code-review.md) is the judgment counterpart to `/code-overview`: orient with the - overview, then evaluate the change with the review. +- [`/code-review`](../../han-coding/docs/skills/code-review.md) is the judgment counterpart to both orientation skills: + orient with the overview or the walkthrough, then evaluate the change with the review. - [Triage and investigate a bug](./triage-and-investigate-a-bug.md) is the matching how-to when the reason you are in unfamiliar code is that something is broken. - [Plan a feature, end to end](./plan-a-feature.md) is the right next step when understanding the code was the prelude to building on it. - The skill long-form docs cover each step in depth: [code-overview](../../han-coding/docs/skills/code-overview.md), +[code-walkthrough](../../han-coding/docs/skills/code-walkthrough.md), [architectural-analysis](../../han-coding/docs/skills/architectural-analysis.md), [investigate](../../han-coding/docs/skills/investigate.md), [project-discovery](../../han-core/docs/skills/project-discovery.md), [project-documentation](../../han-documentation/docs/skills/project-documentation.md), and the Atlassian wrappers From f136bdc9a0b2abac5d0470fc6aa0382237d78d7a Mon Sep 17 00:00:00 2001 From: River Lynn Bailey Date: Mon, 10 Aug 2026 10:07:53 -0600 Subject: [PATCH 4/5] docs: list code-walkthrough in the sizing, concepts, and layout catalogs The new code-walkthrough skill was missing from every enumerated skill list outside the skills index and the han-coding README: the sizing-aware skill lists in docs/sizing.md, docs/concepts.md, and docs/quickstart.md, the per-skill sizing table, the han-coding layout line in CLAUDE.md, and the han-coding roster sentence in docs/concepts.md. Also adds design-an-api to the han-coding roster in docs/concepts.md, which had been missing since that skill shipped. --- CLAUDE.md | 2 +- docs/concepts.md | 5 +++-- docs/quickstart.md | 4 ++-- docs/sizing.md | 26 ++++++++++++++------------ han-coding/README.md | 4 ++-- 5 files changed, 22 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6e25b9e..0d808fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,7 +111,7 @@ han-plugin-builder skill: │ ├── skills/ # Planning skill directories, each with SKILL.md + references/ │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/discussion-facilitator.md │ └── references/ # Both kinds: han-planning-owned canonical files (planning-boundary-rule.md, scope-justification-rule.md, operator-escalation-rule.md) beside vendored copies (yagni-rule.md, evidence-rule.md, config-rule.md). Each owned file opens by saying so; do not overwrite one in a re-sync sweep -├── han-coding/ # Coding plugin: tdd, refactor, design-an-api, code-review, code-overview, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin) +├── han-coding/ # Coding plugin: tdd, refactor, design-an-api, code-review, code-overview, code-walkthrough, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin) │ ├── README.md # Light front door + scent-line skills list │ ├── .claude-plugin/ │ │ └── plugin.json diff --git a/docs/concepts.md b/docs/concepts.md index 11d9006..1e88ef8 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -135,6 +135,7 @@ escalate. positional argument to override (`/code-review medium`, `/plan-a-feature large "describe the feature"`). - **Sizing-aware skills.** [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md), [`/code-overview`](../han-coding/docs/skills/code-overview.md), [`/code-review`](../han-coding/docs/skills/code-review.md), + [`/code-walkthrough`](../han-coding/docs/skills/code-walkthrough.md), [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md), [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md), [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md), @@ -237,8 +238,8 @@ plugins dispatch, the project-discovery skill, and the canonical rule files. `/issue-triage`) plus the research-analyst agent. `han-planning` adds the planning skills you reach for before implementation (`/plan-a-feature`, `/plan-implementation`, `/plan-a-phased-build`, `/plan-work-items`, and `/iterative-plan-review`). `han-coding` adds the coding skills you reach for while working in code (`/tdd`, `/refactor`, -`/code-review`, `/code-overview`, `/architectural-analysis`, `/automated-test-planning`, `/manual-test-planning`, -`/investigate`, and `/coding-standard`). `han-github` adds the GitHub skills, and `han-reporting` adds the reporting +`/design-an-api`, `/code-review`, `/code-overview`, `/code-walkthrough`, `/architectural-analysis`, +`/automated-test-planning`, `/manual-test-planning`, `/investigate`, and `/coding-standard`). `han-github` adds the GitHub skills, and `han-reporting` adds the reporting skills. All of these except `han-reporting` depend on `han-core`, so installing any of them brings the shared agents along; `han-reporting` depends only on `han-communication`. diff --git a/docs/quickstart.md b/docs/quickstart.md index 4614c89..8826a28 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -193,8 +193,8 @@ next. A few that work: ## A note on sizing -The sizing-aware skills (`/architectural-analysis`, `/code-overview`, `/code-review`, `/gap-analysis`, -`/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, `/research`) classify the work as **small**, +The sizing-aware skills (`/architectural-analysis`, `/code-overview`, `/code-review`, `/code-walkthrough`, +`/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, `/research`) classify the work as **small**, **medium**, or **large** before dispatching agents. They default to small, and scale the team and iteration depth to the chosen band. Pass the size as the first positional argument to override (`/code-review medium`, `/plan-a-feature large "describe the feature"`). See [Sizing](./sizing.md) for the full model. diff --git a/docs/sizing.md b/docs/sizing.md index 6fad152..9208408 100644 --- a/docs/sizing.md +++ b/docs/sizing.md @@ -3,8 +3,8 @@ Sizing is one of the two foundational mechanics of the han plugin. Every skill that dispatches a swarm of specialist agents first classifies the work as **small**, **medium**, or **large**. That classification decides how many agents to dispatch, which agents to dispatch, how many rounds to iterate, and how aggressively to calibrate findings. The -sizing-aware skills are `/architectural-analysis`, `/code-overview`, `/code-review`, `/gap-analysis`, -`/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, and `/research`. +sizing-aware skills are `/architectural-analysis`, `/code-overview`, `/code-review`, `/code-walkthrough`, +`/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, and `/research`. > See also: [Plugin landing page](../README.md) · [Concepts](./concepts.md) · [YAGNI](./yagni.md) · > [All skills](./skills/README.md) · [All agents](./agents/README.md) @@ -104,16 +104,17 @@ When the size is overridden with `$size`: ## Sizing across skills at a glance -| Skill | What gets sized | Small | Medium | Large | -| -------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) | Signal-selected roster + finding calibration | Single module, no cross-cutting signal (spine + concurrency, 3–4 agents) | One cross-cutting concern (spine + 1–2 specialists, 4–6 agents) | Multi-subsystem or cross-service seam (spine + all signalled specialists + system-architect, 6–9 agents) | -| [`/code-overview`](../han-coding/docs/skills/code-overview.md) | Exploration roster (codebase-explorer only) | Single file, symbol, or small change set (1 explorer) | A directory/module or moderate change set (2–3 explorers) | Multiple subsystems or a large change set (3–5 explorers) | -| [`/code-review`](../han-coding/docs/skills/code-review.md) | Agent roster + finding calibration | 1–3 files, single subsystem | 3–10 files, one cross-cutting concern | More than 10 files, multiple subsystems | -| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default-on swarm size | 0–3 gaps, single domain (2–3 agents, no PM) | 4–10 gaps, two or three domains (4–6 agents with PM) | 11+ gaps or cross-cutting domains (6–8 agents with PM) | -| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Lightweight vs team mode + specialist cap + round cap | 2–3 files, single system (lightweight, 1 round) | 3–5 files, one cross-cutting concern (team, 1 chosen specialist, 2 rounds) | More than 5 files, multiple systems (team, 2 chosen specialists, 3 rounds) | -| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Review-team size cap | Single subsystem (team cap 2) | Two to three subsystems (team cap 3–4) | Cross-service or security-sensitive (team cap 4–5) | -| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation specialist cap + round cap | Single subsystem (1 chosen specialist, 1 round) | Two to three subsystems (2 chosen specialists, 2 rounds) | Cross-service or security-sensitive (3–4 chosen specialists, 3 rounds) | -| [`/research`](../han-research/docs/skills/research.md) | Research-analyst angle count + reach | One domain, few or no options, narrow reach (2–3 agents) | Two to three domains or several options, codebase-plus-web reach (3–5 agents) | Many options across multiple domains, or full-breadth request (5–8 agents) | +| Skill | What gets sized | Small | Medium | Large | +| -------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) | Signal-selected roster + finding calibration | Single module, no cross-cutting signal (spine + concurrency, 3–4 agents) | One cross-cutting concern (spine + 1–2 specialists, 4–6 agents) | Multi-subsystem or cross-service seam (spine + all signalled specialists + system-architect, 6–9 agents) | +| [`/code-overview`](../han-coding/docs/skills/code-overview.md) | Exploration roster (codebase-explorer only) | Single file, symbol, or small change set (1 explorer) | A directory/module or moderate change set (2–3 explorers) | Multiple subsystems or a large change set (3–5 explorers) | +| [`/code-review`](../han-coding/docs/skills/code-review.md) | Agent roster + finding calibration | 1–3 files, single subsystem | 3–10 files, one cross-cutting concern | More than 10 files, multiple subsystems | +| [`/code-walkthrough`](../han-coding/docs/skills/code-walkthrough.md) | Exploration roster + itinerary length | One file, symbol, or a change across a few files (1 explorer, 3–5 steps) | A directory/module or a change across one or two subsystems (2–3 explorers, 5–8 steps) | Several subsystems, or a change spanning many files across them (3–5 explorers, 8–12 steps) | +| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default-on swarm size | 0–3 gaps, single domain (2–3 agents, no PM) | 4–10 gaps, two or three domains (4–6 agents with PM) | 11+ gaps or cross-cutting domains (6–8 agents with PM) | +| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Lightweight vs team mode + specialist cap + round cap | 2–3 files, single system (lightweight, 1 round) | 3–5 files, one cross-cutting concern (team, 1 chosen specialist, 2 rounds) | More than 5 files, multiple systems (team, 2 chosen specialists, 3 rounds) | +| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Review-team size cap | Single subsystem (team cap 2) | Two to three subsystems (team cap 3–4) | Cross-service or security-sensitive (team cap 4–5) | +| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation specialist cap + round cap | Single subsystem (1 chosen specialist, 1 round) | Two to three subsystems (2 chosen specialists, 2 rounds) | Cross-service or security-sensitive (3–4 chosen specialists, 3 rounds) | +| [`/research`](../han-research/docs/skills/research.md) | Research-analyst angle count + reach | One domain, few or no options, narrow reach (2–3 agents) | Two to three domains or several options, codebase-plus-web reach (3–5 agents) | Many options across multiple domains, or full-breadth request (5–8 agents) | Read each skill's **Sizing** section for the full per-skill rules. @@ -145,6 +146,7 @@ Read each skill's **Sizing** section for the full per-skill rules. - The **Sizing** section in each sizing-aware skill's long-form doc: [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md), [`/code-overview`](../han-coding/docs/skills/code-overview.md), [`/code-review`](../han-coding/docs/skills/code-review.md), + [`/code-walkthrough`](../han-coding/docs/skills/code-walkthrough.md), [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md), [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md), [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md), diff --git a/han-coding/README.md b/han-coding/README.md index 2a4395a..a7f29b1 100644 --- a/han-coding/README.md +++ b/han-coding/README.md @@ -1,8 +1,8 @@ # han-coding The coding layer of the Han suite: the skills you reach for while working in code. It writes code test-first, refactors -it under a green suite, and reviews, overviews, analyzes, tests, investigates, and standardizes it, dispatching -specialist agents to cover each dimension in parallel. Reach for it once there is code to write, change, or judge. +it under a green suite, and reviews, overviews, walks someone through, analyzes, tests, investigates, and standardizes +it, dispatching specialist agents to cover each dimension in parallel. Reach for it once there is code to write, change, or judge. **Bundled.** Installed with the `han` meta-plugin. Depends on `han-communication` and `han-core`. From 3912e7b56a3c02fc1f1c797a374dfa8d5e8261d2 Mon Sep 17 00:00:00 2001 From: River Lynn Bailey Date: Mon, 10 Aug 2026 10:08:56 -0600 Subject: [PATCH 5/5] docs(han-coding): pair code-walkthrough with its siblings in both long-form docs The code-review and code-overview SKILL.md descriptions gained a code-walkthrough boundary on this branch, but their long-form docs still named only each other. Adds the missing boundary bullet and Related documentation entry on both sides so the pairing reads the same in the skill definition and the operator doc. Also corrects code-overview's How to invoke it section, which omitted the dynamic size its argument-hint accepts. --- han-coding/docs/skills/code-overview.md | 8 ++++++-- han-coding/docs/skills/code-review.md | 7 +++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/han-coding/docs/skills/code-overview.md b/han-coding/docs/skills/code-overview.md index 1855a30..9165248 100644 --- a/han-coding/docs/skills/code-overview.md +++ b/han-coding/docs/skills/code-overview.md @@ -68,6 +68,8 @@ to use the skill. For what the skill does internally, read the skill definition - **Assessing architecture, coupling, or structural risk.** Use [`/architectural-analysis`](./architectural-analysis.md) instead. - **Diagnosing a bug or root-causing a failure.** Use [`/investigate`](./investigate.md) instead. +- **Being paced through the code one step at a time.** Use [`/code-walkthrough`](./code-walkthrough.md) instead. It + produces a conversation you drive, not a document you read alone. ## How to invoke it @@ -78,8 +80,8 @@ Give it: 1. **A target (optional).** A file path, a directory, a symbol name, or a pull request reference / URL. With no target, the skill defaults to the current branch's changes in PR mode. A sharp target is a single file, symbol, directory, or PR; a thin one ("explain the backend") forces the skill to ask you to narrow it. -2. **A size (optional).** `small`, `medium`, or `large` as the first positional argument, when you want to override the - skill's auto-classification. +2. **A size (optional).** `small`, `medium`, `large`, or `dynamic` as the first positional argument, when you want to + override the skill's auto-classification. Example prompts: @@ -262,6 +264,8 @@ URL: https://www.spinellis.gr/codereading/ risk assessment rather than an orientation. - [`/investigate`](./investigate.md). Reach for this when something is broken and you need a root cause, not an overview. +- [`/code-walkthrough`](./code-walkthrough.md). The paced counterpart: same understanding goal, delivered as a + step-by-step conversation you can interrupt rather than one document. - [Sizing](../../../docs/sizing.md). The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the `$size` override. - [`codebase-explorer`](../../../han-core/docs/agents/codebase-explorer.md). The agent this skill dispatches, scaled to size, to diff --git a/han-coding/docs/skills/code-review.md b/han-coding/docs/skills/code-review.md index cb6aea7..80975a9 100644 --- a/han-coding/docs/skills/code-review.md +++ b/han-coding/docs/skills/code-review.md @@ -112,8 +112,9 @@ to use the skill. For what the skill does internally, read the skill definition - **Posting the review to a GitHub PR.** Use [`/post-code-review-to-pr`](../../../han-github/docs/skills/post-code-review-to-pr.md). It delegates to this skill and then posts the review as PR comments. -- **Explaining a change or getting oriented before reviewing.** Use [`/code-overview`](./code-overview.md). Run it to - understand what a change does, then run this skill to judge whether it is any good. +- **Explaining a change or getting oriented before reviewing.** Use [`/code-overview`](./code-overview.md) for a written + overview, or [`/code-walkthrough`](./code-walkthrough.md) to be paced through the change one step at a time. Run + either to understand what a change does, then run this skill to judge whether it is any good. - **Architectural analysis.** Use [`/architectural-analysis`](./architectural-analysis.md) for coupling, data flow, concurrency, and SOLID assessment across a module. - **Bug investigation.** Use [`/investigate`](./investigate.md) to find a root cause with evidence and adversarial @@ -422,6 +423,8 @@ URL: https://itrevolution.com/product/accelerate/ GitHub PR. - [`/code-overview`](./code-overview.md). The orientation counterpart: run it to understand a change before this skill judges its quality. +- [`/code-walkthrough`](./code-walkthrough.md). The paced counterpart to `/code-overview`: run it when you want to be + taught the change step by step before this skill judges it. - [`/investigate`](./investigate.md). Next step when a CRIT finding hides a bug whose root cause needs deeper analysis. - [`/architectural-analysis`](./architectural-analysis.md). Run alongside when the change touches module boundaries.