Factory Explain
Giving the user real understanding is what separates owning your software from renting it from an AI. This skill explains what's being built — or what got built — so a smart 10-year-old would follow it: pictures first, analogies always, jargon never.
Three modes:
- Pre-build (factory stage 3→4): explain the plan — what we're about to build and how the pieces will fit. The cheapest moment to catch "wait, that's not what I meant."
- Post-build (after factory-review): explain what actually got built — how it works now that it's real, including anything that changed from plan.
- Standalone: point at any codebase or folder — "explain this like I'm 10" — no factory state needed.
Rules of explanation
- Analogy before mechanism. Every component maps to something from ordinary life — the database is a filing cabinet, the API is a waiter carrying orders to the kitchen, the queue is a take-a-number machine at the deli. Pick ONE coherent scene per explanation (one restaurant, one post office) rather than mixing metaphors.
- Picture before paragraph. Lead every section with a mermaid diagram; prose explains the picture, not the other way around.
- Zero unexplained jargon. Every technical term gets defined in the same sentence, in parentheses, or doesn't appear.
- Follow one thing through the system. The spine of the explanation is a story: "here is what happens, step by step, when you click Save" — from the click to the stored data and back to the screen.
- Honest, not dumbed down. Simplify the language, never the truth. If something is fragile or was parked, the explanation says so plainly.
- End with "what you can now say." Three sentences the user could repeat to a technical person that would be accurate — that's the test of whether understanding transferred.
Structure of one explanation
markdown## <Title: "What we're about to build" | "How <project> works"> ### The whole thing in one picture <mermaid flowchart: 5-9 boxes MAX, plain-language labels — "Saves your items", never "ItemService". More boxes = zoom out further.> ### The cast of characters <each box: what it does, its analogy, where it lives (folder/file)> ### Follow one click through the system <the sequence story — mermaid sequenceDiagram if it earns it> ### The parts most likely to confuse you <2-3 honest gotchas in plain language> ### What you can now say <the three accurate sentences>
Diagram hygiene: quote node labels, keep them under ~6 words, direction top-down for structure and left-right for flows. If the user's setup has a mermaid renderer skill available, offer a rendered image; otherwise the fenced blocks preview fine in Cursor and most markdown viewers.
Accumulate into factory/GUIDE.md
In factory modes, every explanation is appended to factory/GUIDE.md (create
with a one-line intro if missing): pre-build sections under
# Part 1 — The plan, explained, post-build under # Part 2 — What got built, explained, dated. Post-build explanations that supersede a plan
section get one honest line: "We planned X; we ended up with Y because Z."
Over time GUIDE.md becomes the plain-language owner's manual for the
codebase — the file you point a collaborator (or future you) at first.
Interactive close
End every explanation with: "Which part should I zoom into?" — then explain that part one level deeper, same rules, same analogy scene. Depth on demand beats length by default.
In factory mode, update STATE.md's notes line ("plan explained to user " / "build explained ") — the conductor uses it to avoid re-offering what's already been done. If factory/STATE.md doesn't exist (standalone use), create it first with a minimal version of the schema described in factory/SKILL.md.
