aha

AHA · Concept Diagrams

Turn any complex concept into aprogressively layered, big-picture, low-text, interactivestandalone HTML page. The goal is to builda correct mental model — not to mimic baby talk, not to make people "feel like they understand", but to make people "actually understand".

When to Use

Use when: the user wants to truly understand some concept ("talk about X", "what exactly is X", "what's the difference between X and Y"), requests a diagram / visualization / a one-page explanation (including aha), or wants to share a concept explanation with someone else.

Cheap pre-check: if the question can be answered clearly in two or three sentences, answer directly and don't invoke this skill — a full diagram page is meant for concepts "worth five minutes of reading".

Don't use when: ultra-short summaries, one-sentence answers; expert-level deep dives (the reader already knows it; what's missing isn't explanation); rewriting existing documents (that's a document editing task).

Stance (read this first)

1. The user's explicit requirements > this skill's default suggestions. When the user specifies language, audience, file location, explanation scope, or motion preferences, follow the user's instructions.
2. Language follows the language of the user's question.
3. Simplification must not sacrifice accuracy: don't invent precise numbers for facts you're unsure about; note what is inferred and what is unverified.
4. The reader isa smart person who is simply unfamiliar with this field — respect them, don't talk down to them, and avoid "very simple", "obviously", "all you have to do is…".

Seven-layer skeleton (fixed; content can be chosen or omitted)

The learning-science basis for "why it's designed this way" in each layer (advance organizers / structure mapping / testing effect, etc.) is consolidated in references/theory.md（required reading before changing layers, order, or constants; not read during routine generation).

#	Layer	Must achieve
1	One-sentence core	First screen: concept name + one sentence that makes it clear + main visual + starting badge (only marks the level); that sentence has zero jargon, zero formulas — reading it requires no prior setup
2	Why it exists	before/after comparison: what you do without it, what the pain point is
3	Intuition	One analogy + failure boundary(an analogy without a stated failure point is not allowed on the page)
4	Real mechanism	plain language first, terminology later and with consistent meaning throughout;at least one concrete example with real values; core mechanisms have a graphical carrier; process-type ones come with astep simulator
5	Easily confused	Compare 2-3 neighboring concepts by "what each onechanges", each card having an "Output:" line (e.g. "Output: a list sorted by priority")
6	Boundaries and failures	Failure modes get 1-2 character memory tags (same character count across the page, e.g. uniformly 2 characters: "misdelete/missed detection"); misconceptions use the three-part form **"you might think X → actually Y → the dividing line is Z"**
7	Memorize + self-test + ledger	One-sentence formula-style wrap-up, keywords <mark> 2-6 places, no new concepts introduced; then 2-3 self-test questions, answers collapsed by default(at least one question targeting the analogy failure point, one letting readers predict counterexample results); page bottomnumber ledgerlist the sources of ratio-type numbers

A menu, not a template: choose by topic — not every layer must be filled in; if a layer has no value for this topic skip it, but layers 1, 4, and 7 must always be present. Conversely,do not add content with no explanatory value just to pad out layers。

Starting-point calibration (progressive implementation)

Level	Signal	Action
L1 zero foundation	Asks purely in plain language	Standard starting point, analogies drawn from everyday experience
L2 adjacent background	Question reveals an adjacent-domain identity ("I write Rust, explain GC")	Use adjacent domain for bridging analogy, skip the most basic groundwork
L3 already introduced	Already uses this domain's terminology correctly ("gradient descent" used accurately)	Raise the starting point, skip basic analogies, go straight into mechanism and boundaries

Calibration only adjusts the starting point and analogy choice, never deletes layers. If the judgment is wrong, the reader will self-correct after reading one layer further down; but cutting content is irreversible. When the user explicitly specifies the audience, override all signals. The page-top badge only marks the level (起点 L1) — put the one-line basis in small text at the page footer (起点依据：L2 · 提问带 统计背景), so the reader's first screen is not disturbed by calibration meta-information. On L2 pages, state the bridging source at the analogy (pill: "Bridged from: Rust ownership" — do not write "that you're familiar with", the page will be shared with other readers).

Key contracts

Analogy boundaries — each analogy: ① conveys only one mapping; ② marks where it fails, and at least one of the failure points must point tothe real mechanism the analogy conceals (e.g., the glove analogy conceals "the result does not exist before measurement", the room-card analogy conceals "static determination vs dynamic patrol"); ③ after building intuition, still explain the real mechanism; analogies cannot replace mechanism.

Concrete examples — layer 4 has at least one example with real values (hand-calculate a DFT once with 4 sampling points, the D↔E cycle cannot be reached from the root). Plain language lowers the language barrier, but only examples make the abstract land; the two cannot replace each other.

Number discipline + number ledger — key numbers are recomputed on the spot or given a source; ratios of different dimensions must not be mixed in the same sentence (slope ratio ≠ curvature ratio, multiple ≠ percentage point); if a figure is stretched non-uniformly, the caption must note it. Page-bottom ledger (scaffold comes with [data-ledger]): in the body text,each N% / N 倍 must have one entry, data-kind choose one of three — 实算(recomputable in-page, write the formula) / 出处(external source, write the name) / 估算(illustrative values, write assumptions); other key numbers (duration, capacity, count) should also be recorded in the ledger. Percentages inside data tables are not recorded in the ledger (the table itself is structured context; gate 13 exempts numbers inside tables, see "Quality Gates"). If there are no ratio-type numbers, delete all entries and keep the block. Magnitude assertions ("only slow at tens of millions of records", "basically all support it") must likewise either cite a source or be softened to "usually / depends on the implementation". Statements that "look like factual errors" are worse than vagueness —— the credibility of this page rests on every number standing up to recalculation;When the ledger is missing entries, add sources, not remove numbers。

Self-test questions —— questions must not be answerable by restating the layer 7 formula; answers ≤80 characters per question, collapsed by default; only change the text in the scaffold, do not change data-quiz* and hidden(structure is validated by gate 12, see "Quality Gates").

Form selection mapping(wrong form = wasted effort):

To express	Use
Structure / hierarchy	Structure diagram (clearly labeled hand-drawn SVG)
Relationship / comparison	Comparison cards (comparison-cards)
Process / data flow (understandable when static)	Flow diagram (flow-diagram)
A process that happens over time	Step simulator（simulator）
State changes	State diagram or meaningful animation
Continuous field / wave / flow	Static SVG schematic; (optional) vgpu presentation layer

Scale limits(prevents content overload, which slows generation and earns no points): simulator 4-6 steps, SVG nodes ≤ 12, comparison cards ≤ 3, self-test 2-3 questions. The ledger takesfull coverage of ratio numbers in the body textas the priority, keep the number of entries ≤ 6 where possible (when there are more, merge similar items; do not pad the entry count by omitting numbers).

Big graphics, few words: one visual center per section; text keeps only the title, key labels, necessary explanations, and boundaries. It is forbidden to split long body text into multiple text cards and disguise it as visualization. The core mechanisms of layer 4 (object diagram / exchange process / mixing process) must have at least one graphical carrier —— core concepts such as "judge life by the root" and "mix pigments" are not allowed to live only in narration text; strongly visual analogies (mixing paint, rolling a snowball) should be illustrated rather than left as plain text.

Decent animation: animation must show real changes in content or state; it must not just make the finished product blink/pulse/highlight; non-first-screen animations autoplay once when entering the viewport, with pause/step-through/replay retained;prefers-reduced-motion directly output a static result; every animation has a readable static version.

Causal chain: input or condition → what happens → output or impact. Prioritize explaining a small number of interconnected concepts, do not list facts; do not delete key qualifiers that would change the meaning just to be "brief".

Hard rules for form：

• Single-file self-contained, zero remote dependencies at render time (tokens/engine/toolbar/self-test block/ledger are already injected by the CLI)
• Color selection may only use var(--token); outside the tokens block, hex/rgb/hsl are forbidden; for SVG color selection, use any variable already defined in the tokens blockany variable already defined in the tokens block—— commonly used:--cat-a/b/c(and -soft)/ --accent / --warn / --ok / --info(and -soft)/ --t-1…4(text)/ --line、--line-2(wireframe)/ --panel、--surface(fill)
• Page-local layout styles are allowed and often needed(before/after grids, hand-computed tables, SVG dimensions, etc.): put them together in <head> in a newly added <style>, using only var(); do not modify the tokens block, do not modify [SCAFFOLD-STYLE]. For classes already provided by tokens (.card .callout .compare .fails .flow .pipe .analogy .panel .pill .grid-2/3), reuse them first
• The simulator's .sim-node can be added or removed as needed (the engine iterates over all [data-node]), and values must be unique
• Semantic HTML: exactly one <h1>, heading levels must not skip, img must have alt
• Simulator labels follow the page language (except for proper identifiers ClientHello/Q·Kᵀ)
• The main text must not contain questioner references such as "what you asked" (the page will be shared with readers who did not ask the question)

Workflow (three steps)

Model inference is the main time cost (writing about 200 lines of high-quality explanation takes minutes in practice), while tool calls take less than 1 minute. The only things that can be cut are reading files (already zero), browser verification (skipped by default), and exploratory commands (prohibited). The CLI does the construction (boilerplate injection/check/serve); you only do the content creation.

Step 1 · Run one command

The first line of the command output (stderr) will indicate thematching skill version: compare it with the metadata.version at the beginning of this SKILL.md that you are reading — if it is not lower, continue directly; if it is lower, the skill is an old version, so first run the upgrade command given in the output (npx skills add ..., idempotent overwrite), after upgrading you must re-read SKILL.md and start over from Step 1(this generation is invalid, and the scaffold structure may have changed).

npx @dimples/aha new <slug> "<概念名>"

(Version system: the skill itself 1.x / design tokens v1.3.x / npm CLI 0.x are three independent release lines; the version handshake only verifies the skill ↔ CLI pairing, and they do not constrain each other.) <slug> Use lowercase kebab-case (e.g. bayes-theorem), which is part of the filename and URL. The title parameter determines the scaffold lang: when the concept name is pure English but the user speaks Chinese, pass "<英文名>（<中文名>）"(e.g. WebGL（网页图形库）), to avoid having to fix lang afterward.

If the command exits and outputs "storage location selection" (this only appears for first-time/existing users on Windows): relay the given optionsto the user, execute the corresponding aha config ... command according to their choice, and then rerun this command.

Zero skill file reads, zero exploratory commands. Scaffold = canonical tokens + toolbar + engine + seven empty sections (the 7th layer includes a self-test block and a numeric ledger); if left unfilled, it passes all 13 gates. After finishing, go directly to Step 2, do not ls/find/grep the skill directory, do not read any assets / references / cli source code (in practice: anything explored is always significantly slower; the only exception is the files explicitly specified by references/modes.md in optional mode). Readingthe just-generated page itselfis not subject to this restriction — Edit needs an exact old_string, so reading it is necessary.

Step 2 · Fill in all content with chunked Edits

Before writing, define the boundary first (think one line silently, do not put it on the page):This page covers A/B/C of X, not D — it is also the material for the 6th layer "boundary". Then calibrate the starting point (see the previous section), split into natural chunks by content, and4-6 Edits are recommended fill it in completely (do not make small slot-by-slot changes, and do not force merges just to hit the count): ① <head> add a new page-local <style>; ② Start badge 起点 L1 + footer 起点依据：… + seven-slot body inside the container + self-check block + ledger entry (from (SLOT1: to (SLOT8: — 1-7 correspond to the seven layers, SLOT8 is the numeric ledger entry; about 200 lines, can be split into two edits); ③ SIM_STEPS step data. The scaffold determines lang by the title language — when an English title is paired with Chinese content, change lang correctly and merge it into any one of the above edits; do not open a separate step. [SCAFFOLD-STYLE] / [QUIZ-TOGGLE] / [SIM-ENGINE] / [TOOLBAR] four paragraphs keep as-is, not included in the Edit scope; the scaffold's explanatory comments may be kept or deleted, and do not affect the gate. After filling it in, grep the page once to confirm (SLOT / (依据 / (中文标签 no longer appears (try both full-width and half-width, to prevent transcription errors). For content constraints see the above "Seven-Layer Skeleton" and "Key Contracts" — do not read reference.html.

Content self-check (after Step 2 is written → before Step 3, 8 yes/no questions, no tools needed)

Anything you cannot explain clearly is a knowledge gap — fill it before delivering; whichever item you cannot answer, go back to the materials and fill in that item:

1. For every key term in Layer 4, can I say in one plain sentence what it "does"? Does every connection/arrow in the diagram correspond one-to-one with the directions in the mechanism?
2. Does Layer 4 have at least one concrete example with real values, rather than only abstract descriptions?
3. Among the failure points of each analogy, does at least one point to thereal mechanism？
4. For every exact number on the page, have I recalculated it or do I have a source, and have the ratio-type numbers been entered into the ledger?
5. For the neighboring concepts in Layer 5, am I comparing them by "what each changes" rather than listing features?
6. For the misconceptions in Layer 6, do I first name the wrong intuition (you might think X) and then correct it, rather than only stating the correct answer?
7. Layer 7: Does the formula stand on its own for the reader without relying on the preceding text? Can the self-test questions not be answered by restating the formula, and do the answers not copy the original sentences from the body (use different wording/different numbers)?
8. Does every step of the simulator and every state in the diagram fail to contradict the body text (same number/same process)?

Only proceed to Step 3 if all are "yes"; if any is "no" → first revise the content (record honestly in the receipt how many places were changed).

Step 3 · check + delivery (skip browser verification)

npx @dimples/aha check <aha new 输出的路径> && npx @dimples/aha start

13 gates(in check output order): 1. single h1 / 2. headings do not skip levels / 3. head metadata / 4. img alt / 5. tokens consistent with canonical / 6. no color literals outside blocks / 7. semantic classes in the vocabulary / 8. script parseable and no external links / 9. no references to the questioner / 10. failure labels 1-2 characters consistent / 11. simulator labels localized in Chinese pages / 12.self-test block(≥2 questions, answers default hidden)/ 13.numeric ledger(for each N%/N 倍 there is an entry,data-kind valid; percentages in the table are exempt). If the gate fails → fix → rerun,fix only the one problem named each round; if there is no improvement for two consecutive rounds → stop fixing, report honestly. Do not delete content, hide overflow, or shrink font size just to pass the gate. For gate details and known coverage boundaries see references/gates.md(read only when fixing the gate is not working). Known boundaries: the existence of Layers 1/4, the quality of analogy failure boundaries, and the truthfulness of self-checks are backed by the content self-check and the receipt iron rule, with no machine gate; gate 5 compares the comment-stripped core, and historical differences in tokens comment wording (such as old-page comments) are within the tolerance range.

check passes → aha start(idempotent: if not running, start the daemon in the background; if already running, reuse it) → deliver. Do not open the browser screenshot/click simulator by defaultOnly take a screenshot to verify when the user says "check the effect" or reports "the page has a problem", and at that point write the visual verification in the receipt truthfully as passed（已截图核查）. Deliverable = clickable file link(pasting HTML source into the chat does not count as delivery) + receipt.

Delivery receipt (fixed format)

The first two lines of the receipt are based on the actual check output(reuse directly when consistent with it):

check: 13/13 门通过
视觉验证: skipped（默认跳过；说「看效果」即可触发）
校准: 起点 Lx（依据：<一句证据>）
内容自检: 8/8 通过（修正 N 处）
形式门: N 轮

aha start Output only the bookshelf address and the number of pieces N,not including this page's link — write to the user according to the three-line template below (all three lines must be given: direct link to this page / bookshelf entry / the single pitch for fable mode; if the user does not respond, stop there):

http://127.0.0.1:7332/<slug>.html
你历史产生过 N 条概念图解，可以访问 http://127.0.0.1:7332 查看概念书架
如果你还想通过一个寓言故事来方便记忆，请对我说：补充寓言故事

Other commands:npx @dimples/aha serve(local 7332, homepage = concept bookshelf), npx @dimples/aha share(temporary public link).

Optional modes (not used by default; triggered only when the user explicitly requests them)

• Fable story: when the user says "add a fable story" / "add a fable to help me remember" / fable after delivery, read references/modes.md and assets/fable.md, write a ≤1000-word isomorphic fable according to their contract, insert it after the self-test block and before the ledger, and rerun check 13/13.
• vgpu shader display layer: only when the concept's essence is a continuous field/wave/flow and the user explicitly requests something flashier/real-time demonstration; the core explanation never depends on it. For details see references/modes.md。

Anti-patterns (violation means redo)

• ❌ Skipping or faking the content self-check (delivering anyway even though some of the 8 questions are "No")
• ❌ Analogy has no failure boundary; analogy replaces the real mechanism
• ❌ Layer 4 has only an abstract mechanism without an instance with real values
• ❌ Feature-listing comparison (must compare by "what it changes")
• ❌ Misconceptions only state the correct answer without naming the wrong intuition
• ❌ Self-test questions can be answered by reciting formulas; answers are expanded by default; passing the gate after deleting the self-test block
• ❌ Deleting numbers to pass the gate when the ledger is missing entries; labeling estimates as actual calculations
• ❌ Text card arrays disguised as visualization
• ❌ Decorative animations that only blink/highlight; interactions claimed to exist but not implemented
• ❌ Inline colors, modifying tokens, introducing remote rendering dependencies
• ❌ Condescending tone words ("very simple" "obviously" "just")
• ❌ Deleting content / hiding overflow / shrinking font size to pass check — this counts as cheating, not fixing
• ❌ Claiming there was visual verification when there was none

English quick reference

The Chinese sections above are the full contract; this is the command sheet.

1. npx @dimples/aha new <slug> "<concept>" — CLI injects everything; read nothing else (no ls/grep of skill dir, assets, references, cli).
2. Scope the page, calibrate L1/L2/L3, fill slots + SIM_STEPS in 4-6 Edits (~200 lines, colors only via var(--token)), grep no (SLOT remains, answer the 8 self-check questions.
3. aha check <path> 13/13 → aha start → deliver file link + receipt (visual verification stays skipped unless screenshotted).

Optional, never default: fable / vgpu — explicit request only, see references/modes.md. Never: inline color literals, questioner references, decorative-only animation, unverified claims, skipping the self-check.