# Explain Code

> Explains code with C4 model diagrams, analogies, and step-by-step walkthroughs. Use when explaining how code works, teaching about a codebase, onboarding to architecture, or when the user asks "how does this work?", "explain this system", "walk me through this", "what does this code do?", "help me understand this", "show me the architecture", "explain this service", "how is this structured?", "trace the flow", "what happens when X calls Y?", or is new to a codebase and needs orientation. DO NOT USE when: a one-sentence answer suffices — only invoke when an architecture overview, diagram, or step-by-step code walkthrough is the actual need.

- Skill: `bsene/explain-code` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bsene/explain-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bsene/explain-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bsene (https://skillmd.com/u/bsene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bsene/explain-code

---


# Explain Code

## Workflow

1. **Start with an analogy** — compare the code to something from everyday life
2. **Pick the right C4 level** — match diagram depth to the question; default Level 2 (Container)
3. **Draw the diagram** — render it as an ASCII box diagram directly in the response (no external tooling). Pick the C4 level per step 2, then build boxes/arrows with plain characters (`+ - | v ^ <- ->`), keeping lines within ~80 columns so it stays readable in a terminal or chat window. Label each box with the component name (and a one-line responsibility if it fits), and label arrows with the action or event that flows along them.
4. **Walk through the code** — trace inputs to outputs in narrative form: what enters, which functions/modules touch it in order, where state changes, what exits. Name the data, not just the steps.
5. **Highlight a gotcha** — what's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

## Example output shapes

### Single function

> **Analogy:** `debounce` is like a snooze button — it delays acting until you've stopped poking it.
>
> **Walkthrough:** Call starts the timer (`setTimeout`). Another call before the timer fires clears it and restarts (`clearTimeout`). Timer fires → callback executes once.
>
> **Gotcha:** The returned function captures `timer` via closure — each call site needs its own `debounce(fn, ms)` instance, or they'll share the same timer.

### Multi-class system

> **Analogy:** This auth service is like a bouncer at a club — it checks your ID (token) before letting you into any room (endpoint).
>
> ```
> +--------+   token    +----------------+   validate   +-------------+
> | Client | ---------> | AuthMiddleware | -----------> | TokenCache  |
> +--------+            +----------------+              +-------------+
>                                |  claims
>                                v
>                        +---------------+
>                        |  UserService  |
>                        +---------------+
>                                |  user record / UnauthorizedError
>                                v
>                        +---------------+
>                        |   Endpoint    |
>                        +---------------+
> ```
>
> **Walkthrough:** Request arrives at the HTTP adapter → `AuthMiddleware` validates the JWT → decoded claims passed to `UserService.resolve()` → user record returned or `UnauthorizedError` thrown.
>
> **Gotcha:** `AuthMiddleware` is stateless but relies on `TokenCache` — if cache is cold, every request hits the DB.

### Multi-service architecture

> **Analogy:** This checkout pipeline is like a relay race — each service passes a baton (order event) to the next leg before it can proceed.
>
> ```
> +---------------+  order.created   +------------------+  stock.reserved   +-----------------+
> | OrderService  | ---------------> | InventoryService | -----------------> | PaymentService  |
> +---------------+                  +------------------+                    +-----------------+
>        ^                                    |                                      |
>        | compensating event (on failure)    |                                      | payment.captured
>        +------------------------------------+                                      v
>                                                                          +----------------------+
>                                                                          | NotificationService  |
>                                                                          +----------------------+
> ```
>
> **Walkthrough:** `OrderService` emits `order.created` to the message bus → `InventoryService` reserves stock and emits `stock.reserved` → `PaymentService` charges and emits `payment.captured` → `NotificationService` sends confirmation email. Failure at any step emits a compensating event to roll back upstream.
>
> **Gotcha:** Each service is independently deployable but the saga has no central coordinator — debugging a failed order requires tracing correlation IDs across 4 service logs.

---

## Benchmark

Scenario: `.benchmarks/scenarios/explain-code-001-worker-walkthrough.md` · Run: 2026-08-31 · Log: `.benchmarks/runs/2026-08-31/explain-code-001-worker-walkthrough.json`

| Model             | Without | With | Delta |
| ----------------- | ------- | ---- | ----- |
| claude-opus-4-8   | 50%     | 100% | +50%  |
| claude-sonnet-4-6 | 50%     | 100% | +50%  |
| claude-haiku-4-5  | 50%     | 100% | +50%  |

> **PASS (run 2026-08-31)**. Uniform +50 — largest floor lift in this cycle. Gate per `.agents/skills/skill-optimizer/rules/release-gates.md`.