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.