code-walkthrough
Explain a piece of code in execution order — entry point, branches, side effects, the surprising line; cite file:line; not a line-by-line rewrite.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- code-walkthrough
- description
- Explain a piece of code in execution order — entry point, branches, side effects, the surprising line; cite file:line; not a line-by-line rewrite.
03 SKILL.md 正文
code-walkthrough
Trace one execution path through real code. Output is a guided narrative the reader can follow with the source open beside them.
Mode: analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked [TBD] or [VERIFY], never filled in.
When to use
- A new contributor needs to understand how X works.
- A code-review reviewer wants the diff narrated.
- A workflow needs onboarding-ready text.
Inputs
- Path/glob into the code (required).
- Audience tier (per the
explainskill). - Optional: a specific entry point (a function, a route, a test).
Procedure
- Find the entry point. The CLI command, the HTTP route, the test that exercises the path.
- Trace execution in order. Each step: file:line → what happens there → why (if non-obvious).
- Call out side effects — when the path touches the DB, the filesystem, the network, a global, a cache. These are where bugs live.
- Find the surprising line. Every walkthrough has one. Name it and explain why it's there (often a workaround for something).
- Skip the obvious. Loops over arrays don't need narration. Custom error handling does.
- Audience tier: for less-experienced audiences, expand prerequisites inline; for peer audiences, link them.
Output
Code walkthrough: <entry point> — audience: <tier>
Step 1: [file.py:42] receives the request
Inputs: …
What it does: …
Step 2: [file.py:78] validates the auth
Why this not in middleware: <reason, often a quirk>
Step 3: [util.py:15] formats the output
Side effect: writes to <cache key>
Surprising line:
[file.py:103] — `if x is None or x == "":` looks redundant; it's there
because legacy callers in pre-1.0 send "" while new callers send None.
Where the bugs tend to live:
- <file:line> — race between cache write and read.
- <file:line> — silent fallthrough when auth missing.
Quality bar
- Every step cites file:line.
- Side effects called out specifically (cache key, DB table, file path).
- One "surprising line" called out per walkthrough.
- Doesn't narrate obvious code; skips to the interesting parts.
Anti-patterns to avoid
- "Line-by-line" narration of the whole file. Skim what's obvious.
- No file:line citations. The reader can't follow.
- Hiding the surprising line. That's the one the reader most needs to know about.
- Walkthrough that tries to cover three execution paths at once.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).