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.