# Explanation Document

> Structure a codebase/schema explanation as a self-contained HTML document ordered for a READER — mental model and flows first, deep per-component reference last — not in the order you explored it.

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

---


# Explanation document

The deliverable is ONE self-contained `.html` file written in the sandbox and
sent with `sandbox-deliver-files`. Not chat prose, not a ledger dump.

## One document, stable name, survives a sandbox recycle

Give the document a single stable filename and reuse it for the whole run —
`<topic>-explained.html`, never `epoch1.html`, `epoch2.html`, `…-final-v3.html`.
Every pass EXTENDS that one file. A pile of per-pass fragments cannot be merged
later: sandboxes are ephemeral and the earlier ones are gone.

Because the sandbox recycles, treat a missing file as "fresh machine, not blank
slate": if your canonical `.html` is not on local disk when you start, you were
moved to a new sandbox — recover the last version you delivered
(`spaces-thread-attachments` to locate it, `spaces-fetch-attachment` to pull it
back) and extend that, rather than starting over or shipping a stub. Re-deliver
the same filename each time so the newest upload is always the whole document.

## Order it for the reader, not for yourself

You will DISCOVER the system component by component, in whatever order the code
led you. Do NOT ship it in that order. A reader needs to build a mental model
before any detail lands, and the detail has to get progressively deeper — an
appended list of "here's the next file I opened" is an exploration log, not an
explanation. Before delivering, reorganise into this shape, top to bottom:

1. **TL;DR** — 3–5 sentences: what the system is, its one job, and the single
   most important thing to know. A reader who stops here is not lost.
2. **Mental model** — the handful of concepts and the vocabulary. Name the
   actors and the nouns before using them.
3. **End-to-end flows** — the 2–4 paths that actually matter (e.g. "a message
   becomes a desktop notification", "…a mobile push", "…a Slack fallback"),
   each as a numbered walk from trigger to outcome, WITH A DIAGRAM. This is the
   part a reader returns to most; make it the strongest part.
4. **Per-component detail** — grouped by role, not one section per file.
   Cluster (`gateway_*`, producers vs filters vs channels, config vs routing vs
   audit); a flat run of 20+ sections is the inventory this format exists to
   avoid. Each group explains what the flows glossed over.
5. **Deep reference / appendix** — the exhaustive material: per-table field
   notes, payload budgets, queue config, error-code maps, dead-code findings.
   A reader consults this; they do not read it linearly. It belongs at the END,
   never interleaved with the conceptual sections above.
6. **Lookup table** — every entity, one line each, so the document doubles as a
   reference after the first read.

Depth increases as you go down. If a detail is only needed to act on one
specific component, it lives in §5, not §3 or §4.

## Do a consolidation pass before you deliver

Building the document incrementally as paths close is correct — it protects a
capped run. But an incrementally-built document is in discovery order and will
have drifted: out-of-sequence section numbers, the same fact stated twice in
two sections, deep detail sitting above the overview. The LAST thing you do
before `sandbox-deliver-files` is a single pass that:

- reorders sections into the reading order above and renumbers them
   contiguously (a document that jumps 8 → 10 → 22 → 15 was never reorganised);
- merges duplicated explanations and moves stray deep detail down into §5;
- verifies every internal reference and the table of contents still resolve.

## What to record per component

What a reader cannot get from the name: who writes it, who reads it, the
key/uniqueness, the scoping (merchant vs tenant vs reseller), what breaks if it
is wrong, and one concrete example. A sentence that only restates the name
("`gateway_card_info` stores gateway card info") is padding — delete it.

State what you could not determine. An honest gap is information; a confident
guess is a defect a reader inherits.