Explain
Finish when the person could teach it back. Ideas for what to build belong in options.
Inline first
Answer small questions in the conversation. Offer an HTML explainer only when the concept is big enough that the person would want to come back to it or share it, or when they ask for one.
Gather facts before teaching
Read the code yourself for small questions. For a larger trace, give a fresh-context subagent one question to answer with the gather-evidence skill, for example "how does a message travel from the API to the provider, with file references". Give the subagent just that question, and interpret what comes back yourself.
The explainer
Render it with the page house standard. Save it under explainers/ in the work's bundle and add it to the brief's "Related" list. With no brief yet, it gets a bundle of its own.
Sections, in order:
- Title and a one-paragraph gist
- How it works now, told as a story
- One concrete walkthrough: a real request or record from start to finish
- Diagrams: data flow, states, or sequence, whichever carries the idea
- Glossary
- Common misconceptions
- What this is not, and what has not been decided
- Still fuzzy: questions the explainer could not settle
End with next moves as questions only, never as actions:
- Want this turned into a brief?
- Want options?
- Is this actually a bug?
Banned
- Implementation steps, file lists of changes to make, or "next we will implement"
- Recommending a design. If the person asks what to do, that is the
optionsskill. - Editing code
When an explanation changes things
If what the person learns changes the live options, update the options document and its "What we learned" section. If it changes the problem itself, update the brief and tell them you did.


