diff --git a/session-mechanism/references/01-文档索引.md b/session-mechanism/references/01-文档索引.md index 601d1c1..8df85a5 100644 --- a/session-mechanism/references/01-文档索引.md +++ b/session-mechanism/references/01-文档索引.md @@ -31,6 +31,11 @@ | 对方甩来一句没头绪的话 | `02-功能优先协作协议.md` | — | | 只想要速查 | `99-速查清单.md` | — | | **问「这是什么、为什么这样」** | `architecture.md` | — | +| **要把一个话题讲清楚（文字 → 图 → 互动页 三级递进）** | `karpathy-output-ladder/SKILL.md`（**随包子技能**） | — | + +> 📌 **`karpathy-output-ladder/` 是随包子技能**（2026-10-07 按用户令从全局 skills 移入本包 `references/`，内容逐字未改）。 +> ⚠️ **它的"用法"尚未接线**（用户原话「**后续再看如何使用**」）⇒ 现在只做到"**找得到**"： +> 想用它时按上面那行跳过去读它自己的 `SKILL.md`；⛔ **不参与**本包的钩子/判据/自动加载。 ## 二、🔴 文档四条规则（写文档／改文档时必守） diff --git a/session-mechanism/references/karpathy-output-ladder/SKILL.md b/session-mechanism/references/karpathy-output-ladder/SKILL.md new file mode 100644 index 0000000..933359c --- /dev/null +++ b/session-mechanism/references/karpathy-output-ladder/SKILL.md @@ -0,0 +1,101 @@ +--- +name: karpathy-output-ladder +description: "Produce layered explanations that climb Karpathy's LLM output ladder. Rung 1 is tight ASD-STE100 controlled plain text. Rung 2 is a diagram that marks the least-certain part. Rung 3 is a single self-contained interactive HTML page. Use when the user asks to explain, teach, show, or make a visual of a topic and wants the answer to escalate from words to diagram to interactive page, or references Karpathy output ladder or writing hierarchy. Combines controlled prose, diagramming, and standalone HTML delivery in one workflow." +agent_created: true +--- + +# Karpathy Output Ladder (Rungs 1–3) + +## Overview + +Turn any "explain / teach / show me" request into a three-step escalation, in order of +expressiveness and effort: + +- **Rung 1 — Controlled text.** A short, unambiguous explanation written to the ASD-STE100 + controlled-English rules (see `references/ste100.md`). +- **Rung 2 — Diagram.** One SVG or Mermaid diagram that shows the structure, **with the + single most uncertain or assumption-heavy part visibly flagged**. +- **Rung 3 — Interactive page.** One self-contained HTML file (inline CSS + JS, no external + dependencies) that lets the reader explore the topic through tabs, accordions, or toggles. + +Each rung builds on the previous one. A diagram that contradicts the text, or an HTML page +that drops the flagged uncertainty, is a failed deliverable. Always deliver rungs in +sequence and carry the "least-certain" marker up the ladder. + +## When to Use + +Trigger this skill when the user: + +- Asks to explain, teach, clarify, or "show" a concept, mechanism, or process. +- Says "make a diagram / chart / visual" alongside an explanation. +- Wants a standalone HTML explainer, interactive page, or long-scroll infographic. +- References Karpathy's output ladder, the "writing hierarchy", or "rungs" of LLM output. +- Wants a topic rendered at increasing fidelity (words → picture → interactive). + +If the user wants only one rung (e.g. "just a diagram"), still apply the relevant rung's +rules below, but skip the others. + +## Workflow + +### Rung 1 — Controlled text (always first) + +Write the explanation before drawing anything. Follow `references/ste100.md`: + +- Procedural (instruction) sentences: ≤ 20 words. Descriptive sentences: ≤ 25 words. +- Each paragraph: ≤ 6 sentences. +- Prefer active voice. Use one word for one meaning. Keep noun clusters ≤ 3 words. +- Use approved verbs (check, start, stop, use, show, open, close, set, get, make, …). +- No metaphors, no hype words, no double negatives. + +Output a compact block of 3–8 sentences that a non-expert can parse. This block becomes the +caption / intro for Rung 2 and the summary panel for Rung 3. + +### Rung 2 — Diagram with a "least-certain" flag + +Pick the single diagram that carries the idea: + +- **Flow / process / decision** → Mermaid `flowchart` or `sequenceDiagram`. +- **State machine / lifecycle** → Mermaid `stateDiagram-v2`. +- **Spatial / custom / branded** → hand-written inline SVG (viewBox `0 0 680 …`). + +Rules: + +- One concept per diagram. Label every node in plain words. +- **Mark the least-certain part**: dashed border + a `⚠ least certain` tag, or a muted + color, so the reader sees where the explanation is weakest. This is mandatory, not + optional — it is the core discipline of the ladder. +- Keep it minimal; do not decorate. + +If the diagram would need more than ~12 nodes to be honest, split it or fall back to text. + +### Rung 3 — Self-contained interactive HTML + +Copy `assets/html-template/index.html` as the starting point. Then: + +- Keep everything inline: ` + + +
+

Topic Title

+

One-line plain-language subtitle.

+
+
+ +
+

Rung 1 — Plain summary

+

Write 3–8 short sentences here. Active voice. One idea per sentence. + No metaphors. This is the controlled-English core of the explainer.

+
+ + +
+

Rung 2 — Diagram

+ + + Step A + + + Step B + + + + Uncertain + ⚠ least certain + +
+ + +
+ + + +
+

Expand Part 1 here. Keep it short and factual.

+

Expand Part 2 here.

+

Expand Part 3 here.

+ + +
+ Deep dive: how it works +

Put the mechanism breakdown here. One paragraph per details.

+
+ + +
+ ⚠ Least certain: State the one assumption or missing measurement here. Link it to + the dashed node in the diagram above. +
+
+ + + + diff --git a/session-mechanism/references/karpathy-output-ladder/references/ladder-workflow.md b/session-mechanism/references/karpathy-output-ladder/references/ladder-workflow.md new file mode 100644 index 0000000..a0238f7 --- /dev/null +++ b/session-mechanism/references/karpathy-output-ladder/references/ladder-workflow.md @@ -0,0 +1,55 @@ +# Ladder Workflow — Deeper Notes (Rungs 2 & 3) + +Companion to SKILL.md. Use when a diagram or HTML page needs more than the baseline rules. + +## Rung 2 — Diagram selection + +| If the topic is… | Use | Why | +|---|---|---| +| Steps, branches, decisions | Mermaid `flowchart TD` | Fast, readable, no layout code | +| Interaction over time | Mermaid `sequenceDiagram` | Shows actors + order | +| States + transitions | Mermaid `stateDiagram-v2` | Lifecycle clarity | +| Spatial, branded, custom | Inline SVG (`viewBox 0 0 680 …`) | Full control of look | + +Mermaid tips: +- Keep node text short; use `"text"` quotes when labels have punctuation. +- Avoid `graph` with more than ~12 nodes; split instead. +- Render Mermaid by emitting the fenced block for the chat, OR embed via a tiny Mermaid + runtime only if the HTML page needs live rendering (rare — prefer pre-rendered SVG). + +SVG tips: +- Start every SVG with `viewBox="0 0 680 H"`. No fixed width/height in px. +- Use a small palette: 2 strokes + 1 accent + 1 muted (for the uncertain part). +- The "least-certain" node: `stroke-dasharray="6 4"` + `opacity="0.7"` + a `⚠ least certain` + label. This is the non-negotiable marker. + +## The "least-certain" flag — discipline + +For every explanation there is one weakest link: an assumption, a missing measurement, a +contested cause. Find it and mark it on the diagram and in the HTML callout. Do not soften it +with "may" everywhere — mark the one real gap, state the others as plain facts. This is what +separates the ladder from a normal infographic. + +## Rung 3 — Self-contained HTML conventions + +Hard rules: +- One `.html` file. Inline `