total-dumb 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/OyakSaile/im-dump-skill/main/assets/banner.png" alt="total-dumb — the /dumb agent skill explains what your AI is doing right now and why" width="860">
+  <img src="https://raw.githubusercontent.com/OyakSaile/dumb/main/assets/banner.png" alt="total-dumb — the /dumb agent skill explains what your AI is doing right now and why" width="860">
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/npm-total--dumb-CB3837?logo=npm&logoColor=white" alt="npm package total-dumb">
   <img src="https://img.shields.io/badge/node-%E2%89%A5%2018-5FA04E?logo=node.js&logoColor=white" alt="Node 18 or newer">
-  <img src="https://img.shields.io/badge/dependencies-0-4FD1C5" alt="zero dependencies">
   <img src="https://img.shields.io/badge/license-MIT-A78BFA" alt="MIT license">
 </p>
 
@@ -17,44 +16,42 @@
 
 Coding agents are very good at doing the work and very bad at telling you why they are doing it. You watch a migration appear, a job get scheduled, a column get indexed, and the honest answer to "why this, now?" is somewhere in a story file you have not opened.
 
-`/dumb` is an [Agent Skill](https://agentskills.io) that answers that question from where you actually are. It reads the story, its epic and the code around the change, then gives you the step, the bigger picture, an analogy that maps, what a senior would watch for, and where the task resumes. In your language.
+`/dumb` is an [Agent Skill](https://agentskills.io) that answers that question from where you actually are. It reads the story, its epic and the code around the change, then explains in short sentences, one idea at a time, and offers to go deeper only if you want it. In your language.
 
-It works in **Claude Code, Cursor, Codex and OpenCode**, installs with one command, and has zero runtime dependencies.
+It works in **Claude Code, Cursor, Codex and OpenCode**, and installs with one command through a small interactive installer.
 
 ## What it looks like
 
-You are mid-story. The migration just landed. You type `/dumb`:
+`/dumb` writes a full explainer into your repo, then keeps the chat to a few lines and a path. Depth belongs in a document you can scroll, not in a wall of chat text.
 
+Excerpt from `docs/dumb/2026-09-22-retry-webhook-backoff.md`. The real file also carries the system design, every other part, common mistakes, a self-check and a glossary.
+
+```mermaid
+flowchart LR
+  PSP["Payment provider"] -->|"payment.confirmed webhook"| Handler["handlePaymentWebhook"]
+  Handler -->|"the payload"| Order["processOrder"]
+  Handler -->|"row written on failure"| Retries[("webhook_retries")]
+  Retries -->|"rows already due"| Job["Retry job, every minute"]
+  Job -->|"same payload, same key"| Order
 ```
-🧠 What we're doing
-We wrote the `webhook_retries` migration for story 5.6: the table holding every
-failed payment webhook and when to retry it.
-
-🎯 Why (the bigger picture)
-5.6 belongs to Epic 5 (Payments): "a confirmed payment becomes a paid order,
-always". 5.3 (webhook) and 5.4 (idempotency) guarantee the confirmation arrives
-and is not processed twice, but not that it arrives at all if the order processor
-is down that second. Without retry a real payment vanishes, which is why 5.7
-(status screen) is blocked: you cannot show "paid" for something that can
-disappear. AC 2 fixes the shape: 1m → 5m → 25m → 2h, 5 attempts.
-
-🪄 Analogy
-A tracked parcel: if nobody answers, the carrier does not bin it; they leave a
-notice and come back at longer and longer intervals. After 5 attempts it goes to
-the depot (dead letter) and someone collects it.
-
-👀 Senior's eye
-- `next_attempt_at` needs an index: the job asks "what is due?" every minute.
-- Retry without 5.4's idempotency = double payment; reprocessing goes down the
-  same path.
-
-🤔 One question
-Why growing intervals instead of retrying every minute?
-
-➡️ Next step: the job that reads `next_attempt_at <= now()`.
-```
 
-Note what is *not* there: no lecture on what a migration is. Every line names something real from your task. That is the whole design constraint.
+#### Why this exists
+
+Epic 5 promises that a confirmed payment always becomes a paid order, because a customer whose money left their account and whose order still says "pending" will charge back and stop trusting the shop. Today the provider tells us once, and `handlePaymentWebhook` processes it immediately. If the order service is down for that one second, the message is gone and nobody retries, so the payment is lost silently. Story 5.4 already made reprocessing safe to repeat, which is what makes an automatic retry possible at all.
+
+#### handlePaymentWebhook
+
+**In general** — A webhook is one system calling another to announce that something happened, so the receiver never has to ask. The usual alternative is polling, where you ask "is it paid yet?" on a timer, which wastes calls and still adds delay.
+
+**In this project** — The exported function in `src/payments/webhook.ts`. The provider posts the confirmation to it, and it calls `processOrder` straight away.
+
+**How it connects** — The provider feeds it; it feeds `processOrder`. After this story it also feeds `webhook_retries` whenever `processOrder` throws, and the retry job picks up from there.
+
+**❌ Doing it wrong** — Catching the error and returning 200 without storing anything. The provider sees success and never sends the message again, so the payment is lost with no trace to debug.
+
+**✅ Doing it right** — Write the payload to `webhook_retries` before returning, because that row is the only evidence the payment arrived, and the retry job has nothing to work from without it.
+
+Every rule, number and design choice in that file carries its reason. "AC 2 defines 1m, 5m, 25m, 2h" is a failure; the reason those intervals grow is the point.
 
 ## Install
 
@@ -75,20 +72,33 @@ npx total-dumb --dry-run                  # show what would happen, write nothin
 Also available through the `skills` CLI:
 
 ```bash
-npx skills add OyakSaile/im-dump-skill
+npx skills add OyakSaile/dumb
 ```
 
-## Three levels
+## Four levels
+
+Every level except `terms` writes the document. The level sets how deep the document goes and how much the chat asks you.
 
 | You type | You get |
 |---|---|
-| `/dumb` | the six slots above, for a developer who wants the why (~250 words) |
-| `/dumb zero` | for someone who has never seen this before: the analogy carries it, every technical word glossed on first use, no senior section (~300 words) |
-| `/dumb terms` | just the vocabulary: 3 to 8 terms from this step, each with a concrete example from your task |
+| `/dumb` | the full document, then a few lines in chat and one line offering to explain a term or move on |
+| `/dumb zero` | the full document with a wider glossary and an everyday analogy per part; the chat stops and asks which term to explain, plus one question to check you followed |
+| `/dumb senior` | the document without glossary or analogies, with the trade-offs and the alternatives that were rejected; the chat asks nothing |
+| `/dumb terms` | no file, just the vocabulary of this step in chat, each term with an example from your task |
+
+Aliases: `eli5`, `beginner` and `junior` for `zero`; `pro` and `expert` for `senior`; `termos`, `jargon` and `glossary` for `terms`.
+
+With no level given it reads your message. Use the step's terms correctly, or ask a sharp trade-off question, and you get the `senior` treatment. Say "I'm lost" and you get `dev`. It will not offer to define a word you just used correctly.
 
-Aliases: `eli5` and `beginner` for `zero`; `termos`, `jargon` and `glossary` for `terms`.
+You do not have to use the slash command. "why are we doing this?", "what is this for?", "I don't get it", "explain this step" all trigger it mid-task. Ask in any language and both the document and the reply come back in it, headers included.
+
+## What lands in your repo
+
+```
+docs/dumb/2026-09-22-retry-webhook-backoff.md
+```
 
-You do not have to use the slash command. "why are we doing this?", "what is this for?", "I don't get it", "explain this step" all trigger it mid-task. Ask in any language and the answer comes back in it, headers included.
+One file per feature, rewritten when you ask again. Inside: why it exists, the big picture as a labelled Mermaid flow, the system design with the current feature highlighted and the planned connections dotted, a sequence diagram of the main path including the failure branch, then every part with what it is in general, what it is here, what it connects to, a worked example, and a wrong-way and right-way pair. It closes with the common mistakes on this feature, three questions with collapsed answers, and a glossary.
 
 ## Where the "why" comes from
 

package/bin/cli.mjs

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { sep } from "node:path";
 import { stdin, stdout, stderr, exit } from "node:process";
-import { createInterface } from "node:readline/promises";
+import * as p from "@clack/prompts";
 import { AGENTS, AGENT_IDS } from "../src/agents.mjs";
 import { parseArgs, USAGE } from "../src/args.mjs";
 import { detectAgents, install, normalizeAgents, resolveTargets, uninstall } from "../src/install.mjs";
@@ -43,12 +43,38 @@ let scope = opts.scope ?? "global";
 
 const interactive = Boolean(stdin.isTTY) && !opts.yes;
 if (interactive) {
-  const rl = createInterface({ input: stdin, output: stdout });
-  try {
-    if (!opts.agents) agents = await askAgents(rl, detected);
-    if (!opts.scope) scope = await askScope(rl);
-  } finally {
-    rl.close();
+  p.intro(`total-dumb ${pkg.version} — /dumb explains what we're doing and why`);
+  if (detected.length) {
+    p.log.info(`Detected: ${detected.map((id) => AGENTS[id].displayName).join(", ")}`);
+  } else {
+    p.log.warn("No agents detected on this machine. Pick where to install anyway.");
+  }
+
+  if (!opts.agents) {
+    const picked = await p.multiselect({
+      message: "Which agents?",
+      options: AGENT_IDS.map((id) => ({
+        value: id,
+        label: AGENTS[id].displayName,
+        hint: detected.includes(id) ? "detected" : undefined,
+      })),
+      initialValues: detected.length ? detected : AGENT_IDS,
+      required: true,
+    });
+    if (p.isCancel(picked)) { p.cancel("Nothing installed."); exit(0); }
+    agents = AGENT_IDS.filter((id) => picked.includes(id));
+  }
+
+  if (!opts.scope) {
+    const where = await p.select({
+      message: opts.uninstall ? "Remove from where?" : "Where?",
+      options: [
+        { value: "global", label: "Global — this machine", hint: "~/.claude/skills, ~/.cursor/skills, ~/.codex/skills, ~/.config/opencode/skills" },
+        { value: "project", label: "Project — this repo", hint: ".claude/skills, .agents/skills" },
+      ],
+    });
+    if (p.isCancel(where)) { p.cancel("Nothing installed."); exit(0); }
+    scope = where;
   }
 }
 
@@ -62,36 +88,24 @@ if (agents.length === 0) {
 }
 
 const targets = resolveTargets({ agents, scope });
+const spinner = interactive ? p.spinner() : null;
+spinner?.start(opts.uninstall ? "Removing…" : "Installing…");
 let results;
 try {
   results = opts.uninstall
     ? await uninstall(targets, { dryRun: opts.dryRun })
     : await install(targets, { dryRun: opts.dryRun });
 } catch (error) {
+  spinner?.stop("Failed", 1);
   stderr.write(`${error.message}\n`);
   exit(1);
 }
+spinner?.stop(opts.uninstall ? "Removed" : "Installed");
 
 printSummary(results);
+if (interactive) p.outro(results.some((r) => r.status === "failed") ? "Some targets failed." : "Done.");
 exit(results.some((r) => r.status === "failed") ? 1 : 0);
 
-async function askAgents(rl, detected) {
-  stdout.write("\nWhich agents?\n");
-  AGENT_IDS.forEach((id, i) => {
-    stdout.write(`  ${i + 1}) ${AGENTS[id].displayName}${detected.includes(id) ? "  (detected)" : ""}\n`);
-  });
-  const fallback = detected.length ? detected : AGENT_IDS;
-  const suggested = fallback.map((id) => AGENT_IDS.indexOf(id) + 1).join(",");
-  const answer = await rl.question(`Numbers separated by commas [${suggested}]: `);
-  const picked = answer.split(",").map((n) => AGENT_IDS[Number(n.trim()) - 1]).filter(Boolean);
-  return picked.length ? AGENT_IDS.filter((id) => picked.includes(id)) : fallback;
-}
-
-async function askScope(rl) {
-  const answer = await rl.question("Where? (g)lobal for this machine, (p)roject for this repo [g]: ");
-  return answer.trim().toLowerCase().startsWith("p") ? "project" : "global";
-}
-
 function printSummary(results) {
   const verb = opts.uninstall ? "Removed" : "Installed";
   stdout.write(`\n${opts.dryRun ? "[dry-run] " : ""}${verb} the "dumb" skill:\n`);
@@ -102,5 +116,5 @@ function printSummary(results) {
     stdout.write(`  ${icon} ${names.padEnd(26)} ${where}  ${r.status}${r.error ? ` (${r.error})` : ""}\n`);
   }
   const didWrite = results.some((r) => r.status === "installed" || r.status === "updated");
-  if (!opts.uninstall && !opts.dryRun && didWrite) stdout.write("\nMid-task, type:  /dumb   /dumb zero   /dumb terms\n");
+  if (!opts.uninstall && !opts.dryRun && didWrite) stdout.write("\nMid-task, type:  /dumb   /dumb zero   /dumb senior\n");
 }

package/package.json

@@ -1,13 +1,45 @@
 {
   "name": "total-dumb",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent skill that explains what your AI is doing right now and why, with an analogy. One npx install for Claude Code, Cursor, Codex and OpenCode.",
   "type": "module",
-  "bin": { "total-dumb": "bin/cli.mjs" },
-  "files": ["bin", "src", "skills", "README.md"],
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node --test test/*.test.mjs" },
-  "keywords": ["agent-skills", "skill", "claude-code", "cursor", "codex", "opencode", "bmad", "mentor", "learn"],
+  "bin": {
+    "total-dumb": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "agent-skills",
+    "skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "opencode",
+    "bmad",
+    "mentor",
+    "learn"
+  ],
   "author": "Kayo Elias",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OyakSaile/dumb.git"
+  },
+  "homepage": "https://github.com/OyakSaile/dumb#readme",
+  "bugs": {
+    "url": "https://github.com/OyakSaile/dumb/issues"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  }
 }

package/skills/dumb/SKILL.md

@@ -1,83 +1,82 @@
 ---
 name: dumb
-description: Use when the user invokes /dumb or, in the middle of any task (a BMAD story, a refactor, a bug fix, a migration, a config change), asks why the current step exists or what it is for — "why are we doing this?", "what is this for?", "I don't get it", "explain this step", "não entendi", "por que isso?", "explica". Optional level after the name — dev (default), zero, terms.
+description: Use when the user invokes /dumb or, in the middle of any task (a BMAD story, a refactor, a bug fix, a migration, a config change), asks why the current step exists or what it is for — "why are we doing this?", "what is this for?", "I don't get it", "explain this step", "não entendi", "por que isso?", "explica". Optional level after the name — dev (default), zero, senior, terms.
 ---
 
 # dumb — explain the current step and its why
 
 ## Overview
 
-The user is watching work happen and wants to understand it, not just get it done. Reply with a short explanation of what is being done right now and why it matters in the bigger picture, in the user's language, then say where the task resumes.
+An agent is shipping features faster than anyone can read them, and the system design disappears into the diff. This skill exists so the person actually learns it. Write a structured Markdown explainer into the project, then keep the chat short and let the user ask for more.
 
-Core principle: **specific beats correct-but-generic.** Every sentence names something real from this task (the story, the file, the table, the command). "What a migration is" fails; "why this migration must land before story 5.7" passes.
+**Everything has a why.** Every rule, number, acceptance criterion, pattern and design choice you mention carries its reason, in the same sentence or the next. Never "AC 2 defines 1m → 5m → 25m → 2h, 5 attempts". Instead: "AC 2 spaces the retries as 1m → 5m → 25m → 2h because the first one catches a short blip cheaply, the later ones stop hammering a service that is genuinely down, and 5 attempts cap the wait near three hours before a human has to look." If the real reason is not written down anywhere, say so and give the most likely one, labelled as a guess.
 
-## Steps
+**Specific beats correct-but-generic.** Every sentence names something real: the story, the file, the table, the queue.
 
-1. **Pick the level and the language.** The level is the first word after `dumb` in the invocation, else a cue in the message, else `dev`. The language is the one the user writes in this conversation; when the invocation is too short to tell (`/dumb terms`), take it from the surrounding conversation and the project's docs. Every word of the answer is in that language, headers included.
+**One idea at a time.** A reply the user has to decode has failed, however accurate it is.
 
-   | Level | Aliases | Reader |
-   |---|---|---|
-   | `dev` (default) | — | a developer who knows the basics and wants the why |
-   | `zero` | `eli5`, `beginner` | someone who has never seen anything like this |
-   | `terms` | `termos`, `jargon`, `glossary` | wants the vocabulary of this step |
+## Simplicity rules — everywhere
 
-2. **Locate the bigger picture.** Read at most 3 files; stop as soon as every slot of the template can be filled with something specific.
-   - The conversation: what task is in flight and what was just done.
-   - If `docs/stories/` exists (BMAD): the current story file, then its epic file (`docs/epics/`, `docs/epic-*.md`, `docs/prd*.md`, `docs/architecture*.md`).
-   - Otherwise: `README*`, `docs/`, `ROADMAP*`, `docs/adr/`, `CHANGELOG*`, `PLAN*.md`, `TODO*.md`, `AGENTS.md`, `.claude/`.
-   - The code: what calls or depends on the thing being changed.
-   What to pull out of each source is in [references/context.md](references/context.md).
-   Nothing found? The answer opens with one line saying so, before the first section header ("No planning docs found; explaining from the code", in the user's language), then reasons from the code.
+- Short sentences, one idea each.
+- At most one new technical term per sentence.
+- No `term (meaning)` stacks. Definitions belong in the Glossary.
+- No chains of story IDs. One story back, one story forward, in plain words.
+- Analogies only where they help: everyday, 2 sentences at most, mapping one thing.
 
-3. **Fill the template for the level**, in the user's language (headers included). Templates and a worked example are in [references/levels.md](references/levels.md). The `dev` template is below.
+## Steps
 
-4. **Close with `➡️ Next step`** — one line naming where the task resumes. The explanation does not redo, re-run, or re-implement anything already done. If the task was already in progress and the user has not asked to pause, continue it after this line.
+1. **Pick the level and the language.** An explicit level after `dumb` wins; otherwise use step 2. The language is the one the user writes in this conversation; when the invocation is too short to tell (`/dumb terms`), take it from the surrounding conversation and the project's docs. Every word of the document and the reply is in that language, headers included.
 
-## The `dev` template
+   | Level | Aliases | Document | Chat ends with |
+   |---|---|---|---|
+   | `dev` (default) | — | full | "read it first"; after the user has read it, one offer line |
+   | `zero` | `eli5`, `beginner`, `junior` | full, bigger Glossary, an analogy per part | "read it first"; after the user has read it, the check block, then stop |
+   | `senior` | `pro`, `expert` | no Glossary, no analogies, trade-offs in the why | nothing |
+   | `terms` | `termos`, `jargon`, `glossary` | none, chat only | nothing |
 
-```
-🧠 What we're doing
-<1–2 sentences. Names the story / file / function / command being touched right now.>
+2. **Adaptive default.** With no level given, read the user's message. It uses the step's technical terms correctly, or asks a precise trade-off question → `senior`. "não entendi", "I'm lost", "o que é isso", or a bare "why?" → `dev`. Never offer to define a term the user just used correctly.
 
-🎯 Why (the bigger picture)
-<At most 4 sentences: the goal this serves; where it sits (epic, roadmap,
- dependency chain); what breaks or gets harder without it; why now and not later.>
+3. **Find the context, then the parts.** Search order and what to extract are in [references/context.md](references/context.md). Then list the parts this feature touches, by their real names: components, services, queues, workers, agents, tables, endpoints, jobs. Take them from the story or spec and from the code, never from imagination.
 
-🪄 Analogy
-<2–3 sentences. One real-world analogy, each part mapped to one part of this step.>
+4. **Write the document.** If `docs/dumb/*-<feature-slug>.md` already exists, overwrite that file and keep its name, so re-running `/dumb` on the same feature updates one document instead of adding another; otherwise create `docs/dumb/<yyyy-mm-dd>-<feature-slug>.md`, creating the folder if needed. The template, the diagram rules and a worked excerpt are in [references/document.md](references/document.md). Skip this step at `terms`.
 
-👀 Senior's eye
-<2 bullets, one sentence each: trade-offs or pitfalls a senior would watch for right here.>
+5. **Reply in chat**, at most 100 words plus the path. Shapes and dialogue rules are in [references/levels.md](references/levels.md).
 
-🤔 One question
-<One question the user can answer to check they got it. Omit if it would be forced.>
+## The chat reply
 
-➡️ Next step: <one line>
 ```
+<3–5 short lines: what we're doing and why it matters, plain words.>
+
+📄 <path to the file that was written>
+Read the whole document first. When you are done, say so and we go on from there.
+```
+
+At `senior` the last line is omitted. The document carries the depth. The chat carries the invitation. Never paste the document into the chat, and never ask a question or offer terms in this first reply: the user has not read the document yet.
 
-Length: about 250 words. Cut, do not compress.
+## Dialogue
 
-## When the task is a BMAD story, the "why" slot states
+Questions come only after the user says they have read the document ("li", "read it", "done"). At that point the level's ending applies: `dev` sends the single offer line; `zero` sends the check block (terms to pick plus one comprehension question) and stops, even when the same message also says to continue, because at `zero` the check is the gate back to the task; `senior` continues the task with no questions. When the user picks a term, answer in chat, about 80 words: one sentence of meaning, then how it works in this project naming a real file or function, then one tiny example. A wrong answer to the check question gets a different and simpler explanation, then one new question. "entendi" / "got it" closes with `➡️ Next step` and nothing else. Never offer a term the user already knows or already had explained, and stop asking the moment they turn back to the task.
 
-- which epic the story belongs to and what the epic delivers;
-- which earlier stories it builds on;
-- which later stories are blocked by it;
-- the acceptance criterion that carries the motivation.
+## When the task is a BMAD story
 
-This holds at `dev` and `zero`. At `zero` the same four facts are told in the analogy's terms ("the 5.7 screen cannot start until this exists"), not dropped.
+The "why" says which epic the story serves and what that epic delivers, what the most relevant earlier story already built, and the one later story that needs this one. Plain words, never ID arithmetic, and every one of them carries its reason.
 
 ## Honesty
 
-If the motivation is weak, unclear, or the step looks unnecessary, the "why" slot says so. Learning to judge work is part of becoming a better developer.
+If the motivation is weak, unclear, or the step looks unnecessary, say so. Learning to judge work is part of becoming a better developer.
 
 ## Common mistakes
 
 | Mistake | Fix |
 |---|---|
-| Generic lecture ("migrations let you evolve the schema") | Name the table, the story, the story that depends on it |
-| Analogy that decorates instead of maps | Each part of the analogy = one part of the step; if it does not map, choose another |
-| Answering from the conversation alone when `docs/stories/` or a PRD exists | Read the story + its epic first |
-| Replying in English to a user who wrote in another language | Language comes from the conversation and the project's docs, not from the trigger message |
-| Reasoning from the code without saying the planning docs were missing | That line opens the answer, before the first section header |
-| Continuing to implement inside the explanation | The explanation ends at `➡️ Next step`; work resumes after it |
-| Past ~300 words at `dev` | Cut to ~250 for `dev`, ~300 for `zero`; the `🎯` slot is where the padding is |
+| Stating a rule, number or acceptance criterion with no reason | Every one carries its why in the same sentence or the next |
+| Inventing a why that is not in the docs or the code | Say the reason is not recorded, then give the likely one and label it a guess |
+| Pasting the document into the chat | The chat is 3–5 lines plus the path |
+| A part described only as it exists here | Three layers: in general with the usual alternative, in this project, how it connects |
+| Stacked definitions, three `term (meaning)` pairs in a row | Name the term and move on; the Glossary defines it |
+| A chain of story IDs | One story back, one story forward, in plain words |
+| Asking a question or offering terms before the user has read the document | The first reply ends at "read the whole document first"; questions come after they say they read it |
+| Explaining the offered terms at `zero` before the user asks | The check block offers; the user picks; then explain |
+| Quizzing a user who already said they get it, or who asked to continue after the check | Stop asking the moment they turn back to the task; at `zero`, "I read it" still gets the check block once, even with "continue" in the same message |
+| Offering to define a term the user just used correctly | That user is `senior`; give trade-offs instead |
+| Replying in English to a user who wrote in another language | Language comes from the conversation and the project's docs |

package/skills/dumb/references/context.md

@@ -7,7 +7,7 @@ Read at most 3 files. Stop when every template slot can be filled with something
 | Source | Extract |
 |---|---|
 | The conversation | the task in flight; the file / command just touched; what the user already knows |
-| BMAD story file (`docs/stories/<n>.<m>.story.md`, `docs/stories/*<n>.<m>*`) | the "so that" clause; `Depende de` / `Bloqueia` (or `depends on` / `blocks`); the acceptance criterion behind the current task; which task is checked and which is next |
+| BMAD story file (`docs/stories/<n>.<m>.story.md`, `docs/stories/*<n>.<m>*`) | the "so that" clause; the single most relevant story it depends on and the single story it unblocks, to be named in plain words rather than as an ID chain; the acceptance criterion behind the current task; which task is checked and which is next |
 | BMAD epic (`docs/epics/epic-<n>*.md`, `docs/epic-<n>*.md`, `docs/prd*.md` section) | the epic's goal in one sentence; the story list and its order (what comes before and after) |
 | PRD (`docs/prd*.md`) | the product goal the epic serves |
 | Architecture doc (`docs/architecture*.md`) | the technical design or constraint this step has to respect |

package/skills/dumb/references/document.md

@@ -0,0 +1,154 @@
+# The explainer document
+
+Write it to `docs/dumb/<yyyy-mm-dd>-<feature-slug>.md`. Create `docs/dumb/` if it does not exist. If a file matching `docs/dumb/*-<feature-slug>.md` is already there, overwrite that file and keep its name (one document per feature, updated on every run). No file is written at `terms`.
+
+There is no length limit. The document is as long as the parts need: never shorten a part, drop a layer or skip an example to save space. A six-part feature can run past 2,000 words and that is fine. Every section is grounded in this project, with real names. The simplicity rules still apply sentence by sentence, and every rule, number and design choice carries its reason.
+
+Headers below are shown in English, the canonical form; render them in the user's language.
+
+## Template
+
+````markdown
+# <Feature or story name> — explained
+
+## Why this exists
+<4–8 sentences. The goal in plain words. What breaks or gets worse without it.
+Who benefits. Every claim carries its reason. No chains of story IDs.
+At `senior`, also the trade-offs and the alternatives that were considered.>
+
+## The big picture
+<2–3 sentences naming the flow, then the diagram. The diagram never replaces them.>
+
+```mermaid
+flowchart LR
+  A["<part>"] -->|"<what flows>"| B["<part>"]
+```
+
+`<part> → <part> → <part>`
+
+<Then the main walk-through as a sequence diagram, including the failure branch.>
+
+```mermaid
+sequenceDiagram
+    participant A as <part>
+    participant B as <part>
+    A->>B: <what is sent>
+    alt <the thing that can fail> fails
+        B->>A: <what happens instead>
+    else it succeeds
+        B-->>A: <the happy result>
+    end
+```
+
+## System design
+<The components that exist today, how they connect, where this feature plugs in,
+and what is planned next. If no architecture doc exists, derive it from the code
+and say that is what you did.>
+
+```mermaid
+flowchart TD
+  A["<component>"] -->|"<what flows>"| B["<component>"]
+  C["<future component>"] -.->|"planned in story <n>"| B
+  classDef current fill:#fff3bf,stroke:#f08c00
+  class B current
+```
+
+`<component> → <component> → <component>`
+
+## The parts, one by one
+
+### <Part, by its real name>
+**In general** — <1–2 plain sentences: what this kind of thing is and how it works
+anywhere, with the usual alternative for contrast, such as a webhook against polling,
+a queue against a direct call, a worker against doing the work inside the request.
+At `zero`, one everyday analogy here.>
+**In this project** — <file, function, config, real names, and how a message actually
+flows through it here.>
+**How it connects** — <what feeds it and what it feeds, today, and what is planned next.>
+**Example** — <one concrete walk-through with real values.>
+**❌ Doing it wrong** — <a realistic mistake on this part and what breaks because of it.>
+**✅ Doing it right** — <the correct approach and why it works.>
+
+## Common mistakes on this feature
+- <mistake> → <the symptom you would see> → <the fix>
+  <3 to 5 of these.>
+
+## Check yourself
+1. <question>
+2. <question>
+3. <question>
+
+<details>
+<summary>Answers</summary>
+
+1. <answer>
+2. <answer>
+3. <answer>
+
+</details>
+
+## Glossary
+- **<term>** — <one plain line>. <For a component, the three layers in one line each.>
+
+<Omitted entirely at `senior`.>
+
+## Next step
+<One line: where the task resumes.>
+````
+
+## Diagram rules
+
+- At most 10 nodes per diagram. If it needs more, the diagram is at the wrong altitude.
+- Every edge in the big-picture diagram is labelled with **what flows**, not with a verb alone.
+- Use the pipe form for labels, `A -->|"text"| B`, and quote every label. Dotted edges for planned connections, `A -.->|"planned in story 5.8"| B`.
+- Node labels use plain words the reader has already met. A diagram never introduces a new term.
+- One ASCII fallback line goes directly under each `flowchart` block, for readers whose viewer has no Mermaid.
+- A diagram never replaces the sentence that explains it.
+- Style the current feature's parts in the system-design diagram with `classDef current fill:#fff3bf,stroke:#f08c00` and a matching `class` line.
+- Render labels in the user's language.
+- Keep the syntax conservative and re-read every block before finishing. Nothing renders it here, so a typo ships.
+- Use two small `flowchart` blocks for ❌ against ✅ only when the difference is structural, such as a retry loop with and without an idempotency key. Otherwise prose is better.
+
+## By level
+
+| Level | Glossary | Analogies | "Why this exists" | ❌/✅ examples |
+|---|---|---|---|---|
+| `dev` | yes | where they help | goal and consequences | realistic implementation mistakes |
+| `zero` | expanded, every term | one per part, in "In general" | goal and consequences, extra plain | beginner mistakes |
+| `senior` | none | none | plus trade-offs and alternatives considered | design choices, such as at-least-once against exactly-once |
+
+## Worked excerpt
+
+From `docs/dumb/2026-09-22-retry-webhook-backoff.md`, the why and one part.
+
+````markdown
+## Why this exists
+
+Epic 5 promises that a confirmed payment always becomes a paid order, because a
+customer whose money left their account and whose order still says "pending" will
+charge back and stop trusting the shop. Today the payment provider tells us once,
+and `handlePaymentWebhook` processes it immediately. If our order service is down
+for that one second, the message is gone and nobody ever retries, so the payment is
+lost silently. Story 5.4 already made reprocessing safe to repeat, which is what
+makes an automatic retry possible at all. This story adds the place to keep a failed
+message and the schedule for trying it again.
+
+### handlePaymentWebhook
+**In general** — A webhook is one system calling another to announce that something
+happened, so the receiver does not have to ask repeatedly. The usual alternative is
+polling, where you ask "is it paid yet?" on a timer, which wastes calls and still
+adds delay.
+**In this project** — It is the exported function in `src/payments/webhook.ts`. The
+provider posts the confirmation to it, and it calls `processOrder` straight away.
+**How it connects** — The payment provider feeds it, and it feeds `processOrder`
+today. After this story it also feeds the `webhook_retries` table whenever
+`processOrder` throws, and the retry job picks up from there.
+**Example** — A payment clears, the provider posts `{"id":"pay_123","status":"paid"}`,
+the function calls `processOrder` with it, and the order flips to paid.
+**❌ Doing it wrong** — Catching the error and returning 200 without storing anything.
+The provider sees success and never sends the message again, so the payment is lost
+with no trace to debug.
+**✅ Doing it right** — Write the payload to `webhook_retries` before returning, because
+the row is the only evidence that the payment arrived, and the retry job has nothing
+to work from without it.
+````

package/skills/dumb/references/levels.md

@@ -1,82 +1,115 @@
-# Levels — templates and a worked example
+# Levels — the chat reply and the dialogue
+
+The depth goes in the document ([document.md](document.md)). The chat stays short: at most 100 words plus the path. Never paste the document into the chat.
 
 Headers below are shown in English, the canonical form; render them in the user's language.
 
-## `dev` (default) — about 250 words
+## The chat reply, every level except `terms`
 
 ```
-🧠 What we're doing
-<1–2 sentences. Names the story / file / function / command being touched right now.>
+<3–5 short lines: what we're doing and why it matters, plain words,
+ one new technical term per sentence at most.>
 
-🎯 Why (the bigger picture)
-<At most 4 sentences: the goal this serves; where it sits (epic, roadmap,
- dependency chain); what breaks or gets harder without it; why now and not later.>
+📄 <path to the file that was written>
+Read the whole document first. When you are done, say so and we go on from there.
+```
 
-🪄 Analogy
-<2–3 sentences. One real-world analogy, each part mapped to one part of this step.>
+At `senior` the last line is omitted. This first reply never asks a question and never offers terms: the user has not read the document yet. The level's ending below is sent only after the user says they have read it ("li", "read it", "done").
 
-👀 Senior's eye
-<2 bullets, one sentence each: trade-offs or pitfalls a senior would watch for right here.>
+## `dev` (default) — ending, after the user has read the document
 
-🤔 One question
-<One question the user can answer to check they got it. Omit if it would be forced.>
+One line, nothing more:
 
-➡️ Next step: <one line>
 ```
-
-## `zero` — about 300 words, the analogy carries the explanation
-
+Want me to explain <term>, <term> or <term>, or shall we continue?
 ```
-🪄 Analogy
-<3–4 sentences. The real-world analogy first; the rest of the answer refers back to it.>
 
-🧠 What we're doing
-<2–3 sentences. The step, told through the analogy; every technical word appears as
- "term (plain-words meaning)" the first time.>
+If the user says continue, say nothing further and continue the task. If the user picks a term, answer it in chat under the dialogue rules below.
 
-🎯 Why (the bigger picture)
-<2–3 sentences: what goes wrong without it, in the analogy's terms, then in the
- project's terms. On a BMAD story this slot still names the epic, the stories it
- builds on and the story it blocks — in plain words, not numbers alone.>
+## `zero` — ending, after the user has read the document
 
-🤔 One question
-<One question answerable from the analogy.>
+Aliases `eli5`, `beginner`, `junior`. Sent when the user says they have read it, even if that message also says "continue" (at this level the check is the gate back to the task); the reply ends here and **the turn stops**. Do not explain the offered terms yet. The task resumes after the user answers, or after they say they would rather skip the check.
 
-➡️ Next step: <one line>
+```
+🤔 Before we go on:
+1. Want me to explain any of these? <term> · <term> · <term>
+2. Quick question: <one simple comprehension question about this step>
 ```
 
-No `👀 Senior's eye` section at this level.
+## `senior` — ending
 
-## `terms` — 3 to 8 items, no analogy
+Aliases `pro`, `expert`. Nothing, not even the "read it first" line. No question, no offer to define terms. The document carries the trade-offs.
+
+## `terms` — chat only, no file
+
+Aliases `termos`, `jargon`, `glossary`.
 
 ```
 📚 Terms in this step
-- **<term>** — <one-sentence meaning>. Here: <one concrete example from this task>.
+- **<term>** — <one-sentence meaning, with the reason it exists>. Here: <one concrete example from this task>.
 - ...
 
 ➡️ Next step: <one line>
 ```
 
-## Worked example (`dev`, BMAD story)
+Three to eight items, no analogy.
+
+## Dialogue rules
+
+- **A term the user picked** — about 80 words: one sentence of meaning, then how it works in this project naming a real file or function, then one tiny example. Then, at `zero` only, one new question.
+- **A wrong answer to the check question** — do not repeat the same explanation. Explain it a different and simpler way, then ask one new question.
+- **"entendi" / "ok" / "got it"** — close with `➡️ Next step` and nothing else.
+- Never offer a term the user already knows or already had explained.
+- Stop asking the moment the user turns back to the task.
+
+## Worked example — `dev` chat reply
+
+Situation: story 5.6, the `webhook_retries` migration was just written, the user asks "why are we doing this story?".
+
+```
+We just added the table that remembers a payment confirmation we failed to
+process, so a retry can pick it up later. Without it, one second of downtime in
+the order service loses a real payment, because the provider only tells us once.
+I wrote the whole thing up, parts and diagrams included.
+
+📄 docs/dumb/2026-09-22-retry-webhook-backoff.md
+Read the whole document first. When you are done, say so and we go on from there.
+```
 
-Situation: story 5.6 "Retry with backoff for webhook delivery", the migration `webhook_retries` was just written, the user asks "why are we doing this story?".
+The user replies "read it". Only now the offer line:
 
 ```
-🧠 What we're doing
-We wrote the `webhook_retries` migration for story 5.6: the table holding every failed payment webhook and when to retry it.
+Want me to explain webhook, idempotency or dead letter, or shall we continue?
+```
 
-🎯 Why (the bigger picture)
-5.6 belongs to Epic 5 (Payments): "a confirmed payment becomes a paid order, always". 5.3 (webhook) and 5.4 (idempotency) guarantee the confirmation arrives and is not processed twice, but not that it arrives at all if the order processor is down that second. Without retry a real payment vanishes, which is why 5.7 (status screen) is blocked: you cannot show "paid" for something that can disappear. AC 2 fixes the shape: 1m → 5m → 25m → 2h, 5 attempts.
+## Worked example — `zero` chat reply, then one follow-up
 
-🪄 Analogy
-A tracked parcel: if nobody answers, the carrier does not bin it; they leave a notice and come back at longer and longer intervals. After 5 attempts it goes to the depot (dead letter) and someone collects it.
+```
+We created a table called `webhook_retries`. It stores the payment confirmations
+our system failed to handle the first time, so we can try again later. Without
+it, the money leaves the customer and the order never becomes paid.
 
-👀 Senior's eye
-- `next_attempt_at` needs an index: the job asks "what is due?" every minute.
-- Retry without 5.4's idempotency = double payment; reprocessing goes down the same path.
+📄 docs/dumb/2026-09-22-retry-webhook-backoff.md
+Read the whole document first. When you are done, say so and we go on from there.
+```
 
-🤔 One question
-Why growing intervals instead of retrying every minute?
+The user replies "done, read it". Only now the check block:
+
+```
+🤔 Before we go on:
+1. Want me to explain any of these? webhook · idempotency · dead letter
+2. Quick question: if we never saved that message, what would happen to the
+   customer's order?
+```
+
+The user replies "I don't know what a webhook is". Only that term is answered, then one new question:
+
+```
+A webhook is one system calling another to announce that something just happened,
+so we never have to keep asking. Here the payment provider calls our
+`handlePaymentWebhook` function in `src/payments/webhook.ts` the moment a payment
+clears. It arrives once, which is exactly why losing it is expensive.
 
-➡️ Next step: the job that reads `next_attempt_at <= now()`.
+🤔 One more: that function calls `processOrder` straight away. What happens today
+if `processOrder` fails?
 ```