The Bottleneck Isn't Generation. It's Understanding.
A Claude/Cursor skill that turns agent-built diffs, features, and plans into short Sideshow sessions designed so you can actually hold the work in your head.
Agents write faster than I can understand. That used to sound like a boast. Lately it just describes the queue.
I can get a PR, a plan, an investigation, or a half-built feature out of a coding agent in minutes. The part that still takes a human afternoon is reconstructing the mental model: what changed, why it has this shape, which invariants matter, and where to look when it breaks. Generation stopped being the scarce resource. Understanding did.
So I wrote a skill for that bottleneck. It is called /understanding, and it lives at github.com/grqg-dev/understanding.
What the Skill Is For
/understanding takes agent-created work — a diff, a generated feature, an architecture sketch, a plan, an investigation — and turns it into a short Sideshow session. Not a wall of prose. Not a quiz. A progressive explanation with one concept per post, published to a live visual surface the agent already knows how to drive.
The success criterion is not coverage. It is whether I can explain the core idea afterward, predict the important behavior, and know which files to open next. If the session dumps every hunk and every edge case into one scrollable blob, it failed.
I already had /explain-diff for walking a change with HTML, mermaid, and native diff surfaces. This skill borrows that delivery channel and drops the quiz. It is broader than diffs: same pedagogy for plans, reports, and systems, with a harder rule about what earns a post.
The Pedagogy
The skill forces a fixed arc: three to seven posts, one concept each, and every post opens with its one-line takeaway so an expert can read first lines only and still leave with the model.
Orientation first. What is this? Why does it exist? What changed? Why should I care? Before-to-after in one or two sentences. Name the central concept before the supporting cast arrives.
Background in two layers. Deep background that a newcomer can skip. Narrow background that unlocks this work — the exact before-state, invariant, or failure mode. No generic primers. No architecture tours that do not pay rent later.
Core intuition. Contrasting cases first, rule second. Two near-identical examples with real-looking toy data that differ only in the dimension that matters — same input through the old path and the new path — so the reader sees the difference before it gets named. This is straight out of Schwartz and Bransford’s “A Time for Telling”: people cannot perceive the critical feature of an example until they have watched it vary, and a rule that names something you already noticed sticks far better than a rule followed by an illustration. Only then the sentence: “we used to X; now we Y because Z.” Then the refutation: name the wrong assumption a reasonable reader would walk in with — “you might expect X; actually Y” — and correct it head-on. (If no plausible misconception exists, skip it; inventing one is worse than omitting it.) A diagram only when the idea is about flow, state, ownership, timing, or transformation — and diagrams obey a contract from Mayer’s multimedia work: labels on the elements themselves, never in a legend; one accent treatment reserved for the causal path; anything the prose does not reference gets deleted. Then bridge the idea to the one-to-three files or decisions that actually matter.
Walkthrough. One representative scenario end to end. Every step carries a subgoal label — a two-to-four word statement of intent like “establish the invariant” or “hand off ownership” — before the what, why, what-state-changed, and where-in-the-code. That one is Catrambone’s worked-example research: readers who get step lists can replay the trace; readers who get subgoal labels can transfer to the next bug, because they learned the intentions, not the keystrokes. Pivotal steps get framed as the question you would naturally ask at that moment — “what happens if the lookup misses here?” — answered immediately, never left hanging. Show only the lines that connect the mental model to the implementation.
Consequences. Three forced questions, answered only as far as the evidence supports. What is now true — new behavior, impact, what stayed the same. What breaks it — edge cases, trade-offs, and where the simplified model from the intuition post stops matching reality. Where do you go next — the small set of places to inspect when debugging, and the tests backing the claims. End with a compact “mental model to keep” a reader could still repeat a week later, not a recap of every post.
That sequence is most of the product. The rest of the skill is discipline around it: investigate before teaching, separate observed facts from inference, adapt the emphasis for diffs vs plans vs investigations, and never invent a rationale the code does not support.
The Rubric Is a Transfer Test
The first version of the skill ended with a quality checklist — “starts with purpose,” “visuals earn their place,” that kind of thing. Checklists are easy to pass while still shipping an explanation nobody retains. Graded self-scoring is worse: an agent asked to rate its own causality 1–3 hands itself a 3 and moves on.
So the quality bar is now a transfer test the agent runs on itself, silently, before finishing. Using only the published posts — as if it had never done the investigation — it has to answer five questions. What is this and why does it exist, in one sentence? For the central example, what happens now that did not happen before, and what still fails? A bug appears in this behavior tomorrow: which file do you open first, and which post told you? What would a reader wrongly assume, and which post corrects it? Where does the simplified model stop matching reality?
If any answer is missing from the posts or requires going back to the source material, the posts get revised. The reader is never quizzed — the explanation is. That is the difference between a rubric that decorates a skill and one that changes the output: each question has a verifiable anchor in a specific post, so there is nothing to grade generously.
What It Deliberately Does Not Do
It does not quiz. If I wanted spaced repetition, I would open Anki. I want a durable model of the work sitting in front of me.
It does not embed the Sideshow operating manual. The skill calls sideshow agent-howto and sideshow guide once per session and follows those docs. Baking CLI help into every skill is how you get five slightly wrong copies of the same instructions.
It does not auto-trigger. The frontmatter sets disable-model-invocation: true. Mentioning “understand” in an unrelated conversation should not summon a teaching session. This is invoke-only, same family of discipline as the LWC design guide: load the heavy prompt when I ask for it.
Why a Skill Instead of a Prompt
I can type “explain this to me” any time. The problem is that freeform explanation drifts. Agents default to coverage: file lists, hunk-by-hunk narration, polite summaries that never force the causal sentence. Skills are sticky routing plus sticky structure. Once /understanding is installed, the arc above is the default shape of the answer, not a hope I restated at the top of every chat.
That matters more as agents get faster. The cost of regenerating a feature keeps falling. The cost of losing the thread — of shipping something I cannot debug because I never built the model — does not. A skill that spends tokens on orientation and intuition before it spends them on line-by-line walkthrough is a better use of the surplus.
Install it, point it at the last thing an agent made, and keep the mental model instead of the transcript.