bdv-explain-code

name

bdv-explain-code

description

Use ONLY when the user explicitly asks for it — e.g. "explain this code," "walk me through this module/feature/API," "review this for me," "/explain-code," or points at a file/function/snippet and asks what it does. Produces a short, high-level report on existing (already-committed, no-diff) code: what it does, how it's structured, non-obvious behavior, edge cases, risk flags, open questions, and where to look next. Do NOT trigger automatically just because code is present in context or was recently discussed — wait for the user to ask.

Explain Code

Your job is to make unfamiliar, already-written code reviewable in under a minute, without hiding anything that matters. Optimize for the reader's limited attention, not for making the code look clean or complete. This is the no-diff counterpart to the change-report skill — use this one when there is no recent edit to compare against, just existing code to understand.

When this runs

Only when the user explicitly asks — for a feature, module, API, function, or pasted block. Do not run this just because code appeared in the conversation or context; wait to be asked.

If the target isn't clear (which file/module/function), ask before proceeding — don't guess.

Before writing the report

Actually read the relevant code: open the file(s), follow key callers/usages, check related config or types. Don't answer from a skim, from memory of similar code, or from what this kind of code "usually" looks like — ground everything in what's actually there. If you only have time/access to read part of it, say exactly which part in the report.

Output format

Use these exact headings. Bullets, not paragraphs. Only include short code references (function/variable names) when needed for precision — no full snippets or line-by-line walkthroughs.

Summary

1–3 sentences: what this does and why it likely exists, in plain language.

Structure

The key files/functions/components involved and each one's role. Identify the entry point and how control flows between the pieces.

How it works

3–6 bullets on the core logic — decisions, branches, state transitions, data flow. Skip syntax-level detail; focus on what a reviewer needs to reason about correctness.

Non-obvious behavior

Anything a first read would likely miss: side effects, ordering requirements, shared/global state, magic values or flags that change behavior, unusual error handling, implicit assumptions baked into the code.

Edge cases

What's handled vs. not, as far as you can tell: empty/null input, concurrency or race conditions, retries, failures of external calls, size/scale limits. State clearly which of these you actually traced in the code vs. which you're inferring or unsure about — don't blur the two.

Risk flags

Tag each: 🔴 must-check / 🟡 worth a look / ⚪ minor.

Flag: auth/permissions, payments/billing, data mutation or deletion, concurrency, external dependencies/network calls, and anything that looks fragile, tightly coupled, undocumented, or inconsistent with the rest of the codebase.

Open questions

Things you genuinely cannot determine from the code alone — unclear intent, apparent contradictions, or behavior that depends on external context/config you don't have visibility into. If none, say so.

Where to look next

2–4 concrete pointers if someone wants to go deeper — related tests, callers, adjacent modules, or docs worth reading.

Hard rules

• Never claim to understand something you only skimmed. If you read some parts and not others, say exactly which.
• Never reconstruct "plausible" behavior instead of verified behavior — if you didn't confirm it by reading the code, label it as inferred, not fact.
• Prefer surfacing genuine confusion or contradictions over smoothing them into a tidy-sounding explanation.
• If the code is small/simple enough that most sections would be empty, say so and keep the report to a few lines — don't pad it out.