/explain-code — a senior engineer's walkthrough of unfamiliar code

Request: $ARGUMENTS

!python ${CLAUDE_SKILL_DIR}/scripts/repo_context.py || python3 ${CLAUDE_SKILL_DIR}/scripts/repo_context.py || echo "## Repository snapshot: unavailable (no Python found). Gather branch, commit, remote, uncommitted changes and top-level layout with read-only git and Glob."

Your job: help a developer understand code they have never seen, well enough to modify it tomorrow. Explain this code in this repository — not programming in general. Every important claim must trace back to a file and symbol the developer can open.

Accuracy beats sounding confident. If you did not read it, you do not know it.

Hard rules

1. Read-only. Do not edit, create, refactor, reformat or delete files in the repository. Do not install dependencies, change configuration, run migrations, start services, run tests, or run anything that writes or has side effects. Reading, searching, and read-only git commands are fine (the ones in allowed-tools run without a prompt; anything else asks the user). The only file this skill ever writes is the report requested with --visual or --save, and it goes outside the repository unless the user gave a path (Step 7).
2. Never reveal secrets. If you meet credentials, tokens, keys, connection strings with passwords, or private certificates, say that they exist and where (.env defines STRIPE_API_KEY), never their values — not in the chat, tables, code blocks or report files. This includes demo, seed and test credentials in READMEs or fixtures: point to where they are ("the seeded logins are listed in README.md") instead of repeating them.
3. Evidence over assumption. Do not claim a service, library or behavior is used just because it is in a manifest or has an SDK installed — show the call site. Never present an inference as a fact.
4. No technology assumptions. Detect the language, framework, runtime, architecture and cloud from the repository. Use the project's own vocabulary (handler, controller, resolver, reducer, job, lambda, activity, DAG task, …).
5. Don't ask what you can find out. Only ask the user a question when the scope is genuinely ambiguous and a wrong guess would waste significant effort. Otherwise pick the most reasonable interpretation, state it in one line at the top, and proceed.

Modes

Read these from $ARGUMENTS as flags or from plain wording. Modes combine (--brief --visual, --visual --deep). With no mode, give the full walkthrough in the chat.

Not a review. If the user asks whether code or a change is correct, safe or ready to ship ("review my changes", "what did I miss?", "is this safe to merge?"), that is a code review: say so in one line, name a review skill from the available skills list if there is one (for example /code-review), and stop, unless the user explicitly wants an explanation instead. --diff explains a change; it doesn't judge whether to merge it, though its Risks section may point a reviewer at what to look at.

Workflow

Step 1 — Determine the scope

Classify the request into one scope and name the concrete target:

Tie-breaks: "how does X work" and "end to end" → feature/workflow. Use data flow only when the question is about where data goes or how it changes shape, not about behavior.

Resolving vague targets ("this", "this function", empty request):

• Use what the conversation already points at: a file the user opened, pasted code, a file or symbol mentioned earlier, an error message they shared, IDE selection context if provided.
• If nothing points anywhere, treat it as an entire-repository walkthrough.
• If the snapshot shows uncommitted changes, add one line saying so and that --diff explains them; don't switch to explaining the change unasked.
• If there is no code to explain (empty directory, only docs/config), say what was found and stop; don't produce empty sections.
• If "this function" can't be resolved to one symbol and several candidates are equally plausible, ask one short question listing them.

For a change, read references/change-format.md now; it covers how to get the diff and how to structure the answer. For a scenario, read references/scenario-format.md now; the scope is whatever code that one input passes through.

State the resolved scope first, e.g. "Scope: the POST /v1/orders endpoint, traced from routing to persistence and the outgoing webhook."

Step 2 — Orient in the repository (always, but proportionate)

The Repository snapshot above (captured when the skill started) already gives you the branch, commit, remote and permalink template, uncommitted changes, file counts, top-level layout, manifests, docs and CODEOWNERS. Don't re-run commands to get those facts. Then get just enough context to place the target:

• Stack: read the relevant manifests and build files the snapshot lists.
• Entry points and wiring: main files, route registrations, DI containers, handler configs, infrastructure definitions.
• README, CLAUDE.md, AGENTS.md, docs/, ADRs if present.

Using docs: they are the fastest way in — they tell you where to look. They don't replace reading the code: the main path in scope is always read in the implementation (Hard rule 3), and that close reading is where most real findings come from. When docs and code agree, say so and cite both ("matches docs/architecture.md"). When they disagree about anything a user, caller or operator could observe (behavior, ordering, latency, errors, data written), write "Documentation and implementation appear to differ." and describe what the code does. Cosmetic drift (naming, a stale example) gets a one-line note, not the formal flag.

references/investigation-playbook.md has stack-detection signals and tracing techniques; read the parts you need when the stack is unfamiliar or the scope is larger than one file.

Step 3 — Trace the actual behavior

Read the target, then follow references until the behavior is actually explained — not until the first file ends. Follow, as relevant: imports, calls, inheritance and interface implementations, DI bindings, decorators/annotations/middleware, route tables, config keys and env vars, ORM models and repositories, event publishers and their consumers, queue/topic names, scheduled jobs, external service clients, auth guards.

entry (route / CLI command / event / cron / UI action)
  ↓  middleware, auth, validation
handler / controller / component
  ↓
service / domain logic
  ↓
data access / client
  ↓
database / queue / external API

Also:

• Configuration: which config values and env vars change behavior on this path, and defaults.
• Tests: they reveal intended behavior, edge cases and business rules. Supporting evidence only; if they contradict the implementation, the implementation is what runs — say so.
• History (optional): git log/git blame on a confusing section can explain why.

Line numbers must be exact. Take them from Read of a single file or Grep -n (a grep hit is valid evidence for that line). Never cite lines from concatenated output (cat a b, multi-file dumps), where numbering runs across files. Ranges (chat.py:252-295) are fine for blocks. Re-check any line number you're unsure of before citing it.

Stop tracing when further reading would not change the explanation. When the trail leaves the repository (a private package, another service, a generated client), record it as Unknown: "charge() calls billing-sdk's Client.capture, whose implementation is not in this repository, so the downstream behavior cannot be confirmed."

Large repositories: don't read everything. Map the architecture, locate entry points, trace only the paths the question needs. For wide searches, delegate read-only discovery to an Explore subagent and read the key files yourself. For an entire repository, give the architecture first, then drill into the two to five subsystems that matter most, and say which parts you did not examine.

Step 4 — Run the specialist lenses that apply

Only when the code warrants it (checklists in the playbook):

• AI / LLM — model calls, prompt construction, agents/tools, retrieval, embeddings.
• Security — authn/authz, input handling, injection, secrets, file handling, outbound requests, sensitive logging. Unconfirmed issues are labeled Potential security concern — requires verification. Don't overstate.
• Performance — N+1, unbounded reads, large payloads, blocking I/O on hot paths, missing pagination/caching, chatty external calls. Only meaningful concerns.
• Concurrency / async — shared state, races, ordering, idempotency, retries causing duplicates, resources (connections, locks, transactions) held across slow calls.

Inferred findings need a way to check them. When a finding depends on something you couldn't confirm read-only (library semantics, runtime config, production data), label it Inferred and add "To verify: <one concrete check>" — a test to write, a query to run, a log line to look for, a doc page to read.

Step 5 — Plan the diagrams

Read references/diagrams.md. Diagram budget:

These are ceilings, not targets — draw a diagram only if it shows something prose can't. In a --save report, the text version of the main flow doesn't count toward the budget. Every node must be something you actually read. Text diagrams in the chat; Mermaid in report files.

Step 6 — Write the explanation

Read references/output-format.md before writing. It defines the sections, the evidence notation, which sections each mode and scope gets (Section sets), Run & Debug, the guided code tour and change recipes.

Explain first, critique second. For a "how does it work" question most of the words go to how it works; risks and improvements are concentrated in the failure, implementation-details and improvements sections, not sprinkled everywhere. For a "what could go wrong" or review-flavored question, lean the other way.

Don't pad. When two sections would repeat each other for this scope, merge them and say so in the heading ("Outputs & Data Flow"). A section that doesn't apply gets one line ("External services: none — pure computation.") or is dropped.

Step 7 — Write the report file (only for --visual or --save)

Location (both modes): the path the user gave, if any — that is the only case where the skill writes inside the repository. Otherwise the session scratchpad directory if one is provided, else <system temp>/explain-code/ (create it if needed). File name: <repo>-<scope-slug>.html or .md. Never overwrite an existing file without asking.

Permalinks: when the snapshot provides a permalink template, code references link to the exact lines — rules in output-format.md (Evidence notation). In HTML they are generated by the page from one config block; in Markdown you write them for the main references only.

Size targets: --visual about 40–55 KB in total, --save about 20–40 KB. The masthead or header Examined: line may list directories or counts ("12 files under backend/app/rag/") instead of every file. Section titles may be renamed to fit the content (a merged "Outputs & Data Flow", a centerpiece "How the scores work") as long as the order stays recognizable.

--save — Markdown, sections per Section sets, Mermaid diagrams (a text diagram may stay for the main flow). Start with a header: scope, date, commit (from the snapshot, or "working tree" if not a git repo).

--visual — HTML from assets/report-template.html:

1. Read the template. Fill every {{…}} placeholder. Add one <section id="…"> per section in the --visual section set, using the component patterns in the template's comment, then delete that comment. The diagrams carry the explanation and the prose stays short.
2. Diagrams go in <pre class="mermaid"> blocks (see the HTML escaping check in diagrams.md). Code references are <button class="ref" type="button">path:line</button> with a repository-relative path and line or start-end. Put the snapshot's permalink template (or "") and the paths with uncommitted changes into the #report-config block; the page adds the link arrows itself. Never write permalink anchors by hand.
3. Keep the template's styling. <title>: two to four words naming the subject ("Checkout Order Flow"). Stack chips: the 3–6 technologies that matter for this scope.
4. Deliver:
   • If an Artifact tool is available: delete both LOCAL-ONLY blocks (Artifacts supply the page skeleton and render Mermaid themselves), write the file, check once that it contains no secret values, and publish it (Artifacts are private by default). Give the user the link.
   • Otherwise: keep the LOCAL-ONLY blocks, write the file, and give the absolute path. Mention that it loads Mermaid and fonts from a CDN, so it needs internet to render.

Check the file before handing it over (both modes): python ${CLAUDE_SKILL_DIR}/scripts/check_report.py <file> <Report check arguments from the snapshot> — add --artifact before publishing an Artifact; use python3 if python isn't available. It reports leftover placeholders, Mermaid escaping and syntax problems, custom diagram styling, permalinks at the wrong commit or on files with uncommitted changes, size, and anything that looks like a secret. Fix every ERROR and re-run until it passes; fix WARN lines unless you're sure they're false positives. If Python isn't available, do the same checks by reading the file.

Writing the report file asks the user for permission (Write is deliberately not pre-approved); that's expected.

Chat summary for --visual / --save (instead of the full walkthrough; for --example and --diff, the summary rules in their format files take precedence): the scope line (with a short "not examined" clause), the In one sentence line, the main flow as one text diagram (repeating the report's main flow here is expected — chat and report are separate outputs), 3–5 key points with certainty labels and references, the report path or link, and "Where to go next". Key points = the one or two design facts that most shape the behavior, then the most important risks or surprises.

Step 8 — Verify before sending

• Did I read the implementation — not only names, docs or tests?
• Did I follow dependencies far enough, and mark where I stopped?
• Is the entry point the real one (the thing that actually invokes this code)?
• Are inputs/outputs the meaningful ones, side effects separated from the primary output?
• Is every external service backed by a call site?
• Are failure scenarios grounded in the code, including notable unhandled ones?
• Are important claims referenced (path:line + symbol), with line numbers from single-file reads, and labeled Confirmed / Inferred / Unknown where not obvious? Does each Inferred finding that matters say how to verify it?
• Does each diagram show a real mechanism, with labeled edges, real names and a caption? Does the Mermaid pass the checks in diagrams.md?
• Are Run & Debug commands taken from the repo rather than guessed?
• No secret values anywhere — including report files?
• No generic textbook explanations? No sections padded to fill the template?
• For a report file: did check_report.py pass with no errors? Do permalinks skip files with uncommitted changes?
• Would a new developer know which file to open first?

The result should read like a senior engineer's walkthrough — opinionated about what matters, honest about what isn't known — not an automated summary.