feat(han-coding): add the code-walkthrough skill - #176
Merged
Conversation
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.
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.
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.
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.
…g-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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/code-walkthrough, a han-coding skill that walks a person through a set of code changes one step at a time inconversation, stopping after every step so the learner sets the pace.
CLAUDE.md layout and plugin map, the workflows composition chains, the how-to guide for understanding unfamiliar code,
and the sizing-aware skill lists in
docs/sizing.md,docs/concepts.md, anddocs/quickstart.md./code-overviewmost closely. That is the seam this skill has to earn.Why
Han already had
/code-overviewfor understanding unfamiliar code, but it produces one document you read alone. Thatdoes not serve the person who wants to be taught a change and ask questions while it happens, and it is the wrong shape
for onboarding onto a flow you have never traced.
/code-walkthroughcovers that case: it starts at the entry point,follows the execution path, and presents one stop per turn as a heading with the full repository-root-relative path, a
short plain-language explanation leading with why, a small excerpt, and a one-line handoff. Then it stops and waits.
The design decision worth your attention is that a question holds the learner's place rather than advancing it. The
pacing is the deliverable. A learner handed six steps at once is reading a document, which is
/code-overview's job, sothe two skills now name each other as the boundary in both their descriptions and their long-form docs.
Two pre-existing gaps surfaced in lists this branch already touched and are fixed here rather than left for a later
sweep:
/design-an-apiwas missing from the han-coding roster indocs/concepts.md, and/code-overview's "How toinvoke it" section omitted the
dynamicsize itsargument-hintaccepts.How to verify
npm run lint/code-walkthroughon a branch with changes and confirm it presents exactly one step, then stops.next, and confirm the step counter does not move.Risk / rollback
Low risk. The skill is read-only and re-runnable, dispatches only
han-core:codebase-explorer, and writes nothing. Nofeature flag gates it. Everything else in the diff is documentation. Revert with
git revertif the skill's boundaryagainst
/code-overviewturns out to be the wrong split.