12 KiB
ce-explain
Build a dense visual document about a concept, a diff, an idea, or a window of your own recent work. Keep it. Check yourself on it from the document.
ce-explain is the on-demand teaching skill. Point it at something worth understanding and it writes a self-contained explainer, grounded in repo evidence when the material lives here, saved to disk before you are asked where to put it.
It is not a status memo. A recap from this skill is a document you can study or speak from; if you ask for the terse update itself, it declines that form. Ordinary Q&A stays in chat. Operational questions ("why is X doing Y") get a direct answer first, and an explainer is offered only when a real concept sits behind the question.
It also is not ce-compound (that teaches the repo) and not ce-pov (that returns a verdict). The check-in is a Check yourself section at the end of the document, included when you ask for it or the material warrants it; the run never stops to quiz you in chat.
TL;DR
| Question | Answer |
|---|---|
| What does it do? | Classifies the request as concept, diff, idea, or recap, grounds it, writes one visual explainer, then asks where to put it |
| When to use it | You want a document to keep about a change, a topic, an idea, or what you actually did in a window |
| What it produces | One self-contained HTML file (markdown if you ask), written to a temp run dir first, then copied or published if you pick a destination |
| What's next | Keep the file, work through its Check yourself section when it has one, then optional offers into /ce-ideate, /ce-simplify-code, /ce-polish, or /ce-compound-refresh |
Example invocations
Plain language is the ordinary path. Tokens force a mode when inference could go either way.
# Asks what to explain. Offers a recent-work recap as a shortcut
/ce-explain
# A window in prose is a recap, not a topic named "since last Monday"
/ce-explain since last Monday
# Force recap when the prompt could be a window or a topic
/ce-explain since:7d
# Catch yourself up before you speak. Still a teaching doc, not a status memo
/ce-explain catch me up on what I did this week
# Force diff mode on a range
/ce-explain diff:main..HEAD
# A PR, same force
/ce-explain diff:PR#42
# An idea, taken as given. Not scoped, not ranked
/ce-explain my idea of caching explainers per repository
# External concept. No repo grounding
/ce-explain Ruby garbage compaction
# Markdown instead of the default HTML
/ce-explain the parser split output:md
# Someone else will read it. Same depth, not a status memo
/ce-explain write this up for the team audience:team
since last Monday and since:monday resolve to the same window. A colon in a sentence is not a flag: "walk me through the diff: why did we split the parser" is prose, not diff:why.
The Problem
Agent-driven work detaches you from what shipped in two ways.
You cannot account for it. A week of agent commits later, git has the record and you cannot read it in three minutes.
You cannot explain it. Writing the code forced comprehension; reviewing agent output does not, and the debt accumulates on your own projects.
The first wants a report. The second wants a report and, sometimes, a way to make it stick. /ce-compound stores knowledge for the repo and /ce-pov returns a verdict; neither covers this.
The Solution
One artifact contract, four input shapes:
| Input | What you get |
|---|---|
| Work recap ("what did I do this week?") | A date-ordered timeline of real commits, PRs, and the plan or solution docs behind them |
| Diff (a sha, range, PR, or "the last change") | What the change actually does, with annotated hunks and the why per hunk |
| Concept (a topic, subsystem, or external subject) | An explainer grounded in this repo when the topic touches it, fully external when it does not |
| Idea (a proposal of yours) | Implications, mechanics, and trade-offs, taken as a fixed given |
Recap mode dispatches a scout that walks git activity, PRs (only when a PR interface is reachable), and project docs for the window, then writes an evidence file with shas and file:line pointers before any prose is composed. The main conversation does not pre-scan the window. An empty window says so and writes nothing.
Idea mode never scopes (ce-brainstorm) and never ranks alternatives (ce-ideate).
What Makes It Novel
Evidence first, including an honest empty
The scout gathers before anything is characterized, because an early git --all glance would seed a false model of what happened. Unreachable PRs become one honest line, not a guess from branch names. An empty diff: range names what it resolved to and asks before substituting. An external topic with no web access is labeled in the header: Unverified, from model knowledge, not checked against current sources.
Offline, one file, written before the ask
Default output is one self-contained HTML file (markdown via output:md). CSS and SVG are inline, images are data URIs, fonts are system fonts. No scripts, forms, or interactive quiz. A reader who skips every visual still gets the full explanation in prose. The form follows the material: diagram for architecture, annotated snippets for code, numbered flow for a lifecycle, timeline for a recap, two-column contrast for a trade-off.
The header is visible text with fixed field names (Date, Input shape, Subject) so a later library can index them.
The file lands in /tmp/compound-engineering-<effective-uid>/ce-explain/<run-id>/ before the destination ask, so declining every destination loses nothing. That path is temporary; pick a destination if you want to keep the file.
The destination menu comes from this session
The menu offers only what this session actually has. Local file and Leave it are always there. HTML prefers a Claude Artifact in Claude Code when that tool is present, otherwise a public ht-ml.app URL. ht-ml.app is never chosen headlessly, and the option itself warns that the page may be indexed, crawled, copied, or archived. Proof is offered on markdown runs. Thinkroom appears only when that capability is detected.
Written for you, or re-rendered for a reader
Default voice is second person and assumes the context you already have. audience:team (or "write this up for the team") drops second person, names the subject in third person when the evidence supplies a name, and adds the minimum orientation an outside reader needs. Depth, real code, and honesty labels do not change. Wanting to speak from the material (standup prep, meeting prep) stays personal; you are still the reader.
If you compose the personal default and then pick a destination that puts it in front of other people, it offers once to re-render before sending.
The check-in lives in the document
The skill never stops to ask whether you want a quiz, and never poses questions in chat. When you ask for a check-in, or the material warrants active recall (a gnarly diff, a hard concept, a dense recap window) and you did not decline one, the document ends with a Check yourself section: two to four questions listed first, then their answers under an Answers label, so you can attempt every question before any answer is in view. Each answer says what a correct response contains and names the gap a plausible wrong answer exposes. Routine material gets no section.
Saying "no quiz" omits the section; asking for one includes it whatever the material.
Quick Example
You type /ce-explain since last Monday. That is a recap. A scout walks the window and writes evidence with shas. The week has real commits, so a document is composed: a timeline, each entry naming what changed and why it mattered.
The material is routine, so the document carries no Check yourself section. The HTML lands in the run dir, you are asked where to put it, and you pick a local file and open it.
The evidence includes a plan that shipped work has since contradicted. After the destination is settled, the skill offers /ce-compound-refresh on that doc. Take it or leave it.
When to Reach For It
Use ce-explain when:
- You need a written breakdown of a change you did not type, to keep
- You want to learn a concept or subsystem, in this repo or outside it
- You have an early idea and want its implications laid out before committing to it
- You cannot account for a window of your own work and want a document you can study or speak from
Skip it when:
- You want a standup blurb or status memo. This skill will not write one, though recap mode can catch you up so you can
- Ordinary Q&A, a quick "why?", or a trade-off that belongs in chat
- Operational diagnosis ("why is X doing Y") unless you then accept the explainer offer
- You need a verdict on whether to adopt something →
/ce-pov - The knowledge belongs to the repo's future work →
/ce-compound
Use as Part of the Workflow
ce-explain sits outside the core loop. Invoke it when your account of the work, or your understanding of it, lags behind what shipped.
Closing offers, only after the destination is settled:
- New-capability ideas →
/ce-ideate - Code-clarity findings →
/ce-simplify-code - UI/UX polish → you invoke
/ce-polishyourself (ce-polishis user-invoked only) - A plan or solution doc the evidence has overtaken →
/ce-compound-refresh
Those are offers, never auto-fired. An unattended run reports the temp path and skips them.
Use Standalone
No plan and no brainstorm required. It works in any repo, and with no repo at all for an external topic.
A bare /ce-explain asks what to explain. It does not invent a default artifact.
Reference
| Argument | Effect |
|---|---|
| (empty) | Asks "What should I explain?" and offers a recap shortcut |
| free text | Classified as concept, idea, diff, or recap by shape |
diff:<ref-or-range> |
Force diff mode (diff:abc1234, diff:main..HEAD, diff:PR#42) |
since:<window|date|ref> |
Force recap mode (since:monday, since:7d, since:v2.1.0). Last 7 days only when no window was named |
output:md |
Markdown artifact instead of HTML (output:html forces HTML) |
audience:<who> |
Render for that reader instead of you personally |
A token in flag position beats inference; a colon inside a sentence does not. diff: and since: together conflict, and the skill asks which you meant. An unrecognized word:value (including feat: inside a topic) stays as request text.
FAQ
Do I have to do the quiz?
No. The Check yourself section sits at the end of the document for whenever you want it, and the run never waits on you for it. Say "no quiz" and the section is omitted; routine material gets none anyway.
Can I use this for standup?
Recap mode can catch you up so you can speak; the skill will not write the status update itself. If the document is going to a team, say so (or pass audience:) and it renders for them at full depth.
Can I share the report? Yes. Ask for that audience up front, or take the re-render offer when you pick a shared destination.
Where does the artifact go?
$RUN_DIR under /tmp/compound-engineering-<effective-uid>/ce-explain/ first. A destination copies or publishes it; leave it and the path is temporary.
Is this ce-compound for humans?
Roughly. A Learning teaches the repo's future work; an explainer documents something for you. They are complements.
Can it track what I have learned?
Not in v1. No library, no spaced repetition, no progress state. The Check yourself section is yours to revisit; the stable run-dir layout and fixed header fields are what a later library could build on.
See Also
ce-pov: a verdict on something external, not a document about itce-compound: knowledge that belongs to the repoce-ideate: where new-capability observations can go nextce-simplify-code: where code-clarity findings can go nextce-polish: late polish you invoke yourselfce-compound-refresh: a plan or solution doc the recap just contradicted