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

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