Explain Code

Explain what code observably does at the requested scope, whether a change before merge, a function, a subsystem, an end-to-end flow, the whole system, or another slice. The explainer is the deliverable. Optional follow-ups include Q&A on what remains unclear, a quiz to uncover misunderstandings rather than certify mastery, and a micro-world, a small interactive simulation for logic that prose and diagrams cannot convey.

Boundaries

• Explain only. Never judge code quality, never edit the project's code or comments, never run the project's code. A micro-world (step 8) is a separate throwaway simulation, not an exception.
• If something looks buggy or suspicious while reading, note the observation in one line and suggest a code review; do not develop it into review findings.
• If confusion stems from unclear code rather than from the target itself, say so and suggest a documentation or simplification pass; do not fix the code here.
• If the user wants proof the code works, suggest runtime verification; this skill checks the user's understanding, not the code's correctness.

Workflow

1. Resolve the requested scope. Any slice of code is valid. State the resolved scope in one line at the top of the explainer so a misread surfaces immediately.
   • Change: a diff. Default to the current branch plus working tree against its merge base with the default branch; accept an explicit commit range, PR, staged changes, or file set. The diff is the ground truth. If it is empty, report that there is nothing to explain and stop.
   • Part: a named function, class, module, feature, subsystem, directory, or file set. Resolve which files or regions implement it by reading, not guessing; if the name maps to several plausible units, name the mapping you chose.
   • System: the whole codebase or a whole service.
   • Anything else: an end-to-end flow, a cross-cutting concern (error handling, authentication), a scenario ("what happens on login"). Resolve it to the implementing code and borrow the nearest anchor's guidance.
   • When the request is ambiguous ("explain this"), infer from context — a just-completed change means change scope, an open or named file means part scope — and say what you resolved.