Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

docs(skills): enforce STE-80 writing and add the /explain skill

naveenkash6568ff6e78bd
diff --git a/.ai/specs/AGENTS.md b/.ai/specs/AGENTS.md
index 42d6f611f3..27897b3386 100644
--- a/.ai/specs/AGENTS.md
+++ b/.ai/specs/AGENTS.md
@@ -27,7 +27,7 @@ Check `.ai/specs/` before modifying any module. Create or update specs when the
3. Spec written in .ai/specs/{YYYY-MM-DD}-{title}.md with resolutions baked in
(questions surfaced while writing go back to step 2 before the spec is final)
4. Implementation proceeds phase-by-phase
-5. Completed spec moves to .ai/specs/implemented/
+5. Completed spec moves to .ai/specs/implemented/ (with its /explain .html, if any)
6. PR links back to spec via "Tracking spec:" line
```
@@ -53,6 +53,12 @@ Examples:
| Small bug fix or typo | Skip spec |
| One-file refactor, no behavior change | Skip spec |
+## HTML explainers
+
+A spec may have a sibling `{same-name}.html` made by `/explain`. The `.md` is
+the source of truth. After you edit a spec, find the stale pages with the
+loop in `/explain` → "Keeping pages fresh", and regenerate each one.
+
## Spec Template
Use `.ai/specs/template.md` as a starting point for new specs.
diff --git a/.ai/specs/template.md b/.ai/specs/template.md
index b083939ae4..e6885ae343 100644
--- a/.ai/specs/template.md
+++ b/.ai/specs/template.md
@@ -8,6 +8,18 @@
One paragraph summary of what this spec proposes.
+## Overview diagram
+
+One Mermaid diagram that explains the whole change. Choose its type with the
+table in `/spec-writing` Step 6. Replace this sample.
+
+```mermaid
+flowchart LR
+ A["Current step"] --> B["Changed step"]:::hot --> C["New step"]:::new
+ classDef hot stroke-width:3px
+ classDef new stroke-dasharray:4 3
+```
+
## Problem Statement
What's wrong or what's missing. Include concrete examples if possible.
diff --git a/.claude/rules/writing-ste.md b/.claude/rules/writing-ste.md
new file mode 100644
index 0000000000..2c1cda3134
--- /dev/null
+++ b/.claude/rules/writing-ste.md
@@ -0,0 +1,146 @@
+---
+paths:
+ - ".ai/specs/**"
+ - ".ai/plans/**"
+ - ".ai/research/**"
+ - ".ai/runs/**"
+---
+
+# Writing style for specs, plans and explainers — "STE-80"
+
+Prose in `.ai/specs/`, `.ai/plans/`, `.ai/research/`, `.ai/runs/`, every
+`/explain` page, and the hand-off message that presents any of them follows
+**STE-80**: about 80% of the way to ASD-STE100 Simplified Technical
+English, the controlled language that aerospace maintenance manuals use. The
+full standard is too strict for design work. STE-80 keeps the rules that make
+text easy to read and drops the rules that would distort Carbon's vocabulary.
+
+Why: a reader must understand a spec or a plan fast and in one pass. Long
+sentences, passive voice and noun stacks hide who does what. A weak executor
+model also follows short, literal instructions much better than an essay.
+
+Scope: prose only. Code, SQL, identifiers, commands and quoted error text stay
+exact.
+
+## The rules (keep these)
+
+| # | Rule | Limit |
+|---|------|-------|
+| 1 | Procedural sentence (an instruction) | max **20 words** |
+| 2 | Descriptive sentence (a fact, a reason) | max **25 words**; a rationale may go to 30 |
+| 3 | One instruction per sentence | split "do X and then do Y" into two steps |
+| 4 | Instructions use the imperative | "Run the migration.", not "The migration should be run." |
+| 5 | Active voice | name the actor: "The trigger sets `status`", not "`status` is set" |
+| 6 | Paragraph | max **6 sentences**, one topic |
+| 7 | Sequence of actions | numbered vertical list, one action per item |
+| 8 | Condition before action | "If the job is Paused, skip it." |
+| 9 | Warning before the step it guards | put the 🛑 / caution line first, then the step |
+| 10 | One word, one meaning | pick a term and keep it; never alternate synonyms for variety |
+| 11 | Simple word over complex word | use, start, end, help, show, about — not utilize, commence, terminate, facilitate, demonstrate, approximately |
+| 12 | No noun clusters longer than 3 words | "the date the supplier confirms the order", not "supplier order confirmation date value" |
+| 13 | Keep articles | write "the", "a"; telegraphic text ("Update row, return id") is allowed only inside numbered Steps lists and task `<summary>` lines |
+| 14 | Simple tenses | present for facts, imperative for instructions, future only for planned behavior |
+| 15 | No vague quantities | a number, a column name, or a named state — never "some", "various", "etc.", "as appropriate" |
+
+## The 20% we drop (Carbon exceptions)
+
+- **Domain terms are approved words.** Use the canonical term from
+ `docs/content/src/glossary/terms.ts` (Make to Order, Pull from Inventory,
+ Backflush, Lineside, Supersession) even when STE's dictionary has no entry for it. Do not
+ replace a domain term with a "simpler" word — that creates rule 10 violations.
+- **Identifiers in code font are approved words.** `jobMaterial`,
+ `settleConsumeFirstLines`, `companyId` count as one word each.
+- **`-ing` forms and phrasal verbs are allowed** when the alternative reads
+ worse ("set up", "picking list"). STE forbids them; STE-80 does not.
+- **Tables are preferred over prose** for any comparison, decision or mapping.
+ A table cell does not need to be a full sentence.
+
+## Before → after
+
+| Before | After (STE-80) |
+|--------|----------------|
+| "It should be noted that in the event that the predecessor has insufficient stock to cover a whole assembly, the line will be redirected to the successor." | "If the predecessor's stock covers no whole assembly, the line moves to the successor." |
+| "Utilize the existing service function to facilitate retrieval of the data." | "Use `getJobMaterialItemIds` to read the item ids." |
+| "Validation and persistence of the supplier quote line price break quantity value occurs in the action." | "The route action validates the quantity of each price break. Then it saves the row." |
+| "Various edge cases etc. should be handled appropriately." | "Handle 3 cases: quantity 0, a deleted item, and a cancelled job." |
+
+## Enforcement — every time, no exceptions
+
+STE-80 is a gate, not a guideline. It applies to every file you write or
+change under `.ai/research/`, `.ai/specs/`, `.ai/plans/` and `.ai/runs/`, and to
+the message that hands any of them to the human. It applies in every mode:
+supervised, autonomous `/feature`, `/conductor`, and headless runs.
+
+**STE-80 is the author's job, never the human's.** The human reviews the
+decisions in a document. The human never checks its style. So:
+
+- Write in STE-80 from the first sentence. Never draft in ordinary English
+ with a plan to convert it later.
+- Finish the review pass below yourself, before the human sees the file.
+- Never ask the human to check STE-80, and never hand off a file "for an
+ STE-80 review". If you cannot make a passage pass, rewrite it until it does.
+- Never report a file as done while one self-check box is still unticked.
+
+### Write-time habits
+
+Use these as you write each sentence, not afterwards:
+
+1. Start with the actor: "The route action saves the row", "SAP prints the certificate".
+2. One fact or one instruction per sentence. Put a full stop where you would write "and".
+3. Put the condition first: "If X, do Y."
+4. Turn every sequence into a numbered list as you write it.
+5. Use the term you used before. Do not switch to a synonym.
+6. Write a number or a name, never "some", "various" or "etc.".
+
+### The review pass
+
+Do the **STE-80 review pass** on each such file before you hand it off or
+mark a phase done. Do it again after every later edit to the file.
+
+1. Read the whole file, one paragraph at a time. Skip code blocks, SQL,
+ tables, headings and the Sources list.
+2. For each sentence that runs past about two lines, count its words. A word
+ in code font counts as one word.
+3. Split each instruction over 20 words and each descriptive sentence over 25
+ words. A rationale may go to 30.
+4. Find each "is / are / was / were / be / been + past participle". If it hides
+ who acts, rewrite it with the actor as the subject.
+5. Split each paragraph that has more than 6 sentences.
+6. Search the file for "etc.", "various", "some", "as appropriate", "TBD",
+ "utilize", "facilitate", "approximately". Replace each one with a number,
+ a name or a simpler word.
+7. List the key terms of the document. Make sure each concept has one name only.
+8. Do the self-check list at the end of this file. Tick every box before you
+ continue.
+
+**Subagent output is raw material, not finished prose.** A subagent does not
+follow this rule unless you tell it to, and it writes its report for you, not
+for the reader. So:
+
+1. In every subagent prompt that returns prose for a document, add: "Write your
+ report in STE-80 (`.claude/rules/writing-ste.md`)."
+2. When the result arrives, never paste it into the document as it is. Rewrite
+ each part in STE-80 and in the document's own terms.
+3. After you merge a subagent's result into a document, do the STE-80 review
+ pass on that document again, before any other step.
+4. If a subagent edits a document directly, do the review pass on that
+ document yourself when the subagent reports back. Do not trust the
+ subagent's own claim that the prose is clean.
+5. Check the facts too. A rewrite can turn a careful claim into a false
+ general one ("ProShop and E2 print it" → "all products print it").
+
+Red flags — each one means you are about to skip the gate:
+
+- "The subagent's summary is already clear, I'll paste it."
+- "It's only the research file; the spec is what people read."
+- "Autonomous mode, no reviewer, I'll check at the end."
+- "The subagent says it followed STE-80, so I can skip the review pass."
+- "It's a small edit, no need for another review pass."
+
+## Self-check before you finish a document
+
+- [ ] No instruction sentence over 20 words, no descriptive sentence over 25 (30 for a rationale)
+- [ ] No passive sentence that hides the actor
+- [ ] Every multi-step action is a numbered list
+- [ ] Each concept has exactly one name in the whole document
+- [ ] No "etc.", "various", "as appropriate", "TBD"
diff --git a/.claude/skills/README.md b/.claude/skills/README.md
index c30cadcc5a..50ac6e5a9f 100644
--- a/.claude/skills/README.md
+++ b/.claude/skills/README.md
@@ -69,6 +69,7 @@ in root-cause, BLOCKED in fix) always surface to the human.
| `translate` | Fill missing i18n .po translations via cheap Haiku subagents | `packages/locale/locales/*/*.po` |
| `test-driven-development` | Red→green→refactor discipline (vitest) | tests-first code |
| `writing-skills` | House guide for authoring skills | skills |
+| `explain` | HTML explainer (STE-80 prose + one diagram) for a spec, plan or research file | `{source}.html` beside the `.md` |
| `pr-explainer` | Self-contained HTML review aid for a PR | `.pr-review/*.html` |
| `pr-splitter` | Split a large PR into reviewable stacked PRs | branches + split notes |
| `carbon-design` | Carbon's design language: principles, page archetypes, components, states, copy, anti-patterns + mandatory design review for any ERP/MES UI | design brief + reviewed UI |
@@ -83,6 +84,11 @@ in root-cause, BLOCKED in fix) always surface to the human.
- Typecheck is always scoped: `pnpm exec turbo run typecheck --filter=<pkg>`.
Whole-repo typecheck OOMs — no skill may prescribe it.
- `pnpm run generate:types` after any migration, before typechecking.
+- Every file a skill writes under `.ai/research/`, `.ai/specs/`, `.ai/plans/` or
+ `.ai/runs/`, and its hand-off message, is written in STE-80 from the first
+ draft and passes the STE-80 review pass. The human never checks the style. The skill rewrites subagent results in STE-80
+ before they go into a file, and repeats the review pass after every merge
+ (`.claude/rules/writing-ste.md` → Enforcement).
- Commits only through `/check-and-commit` (explicit file staging, conventional
messages); push only when the branch tracks a remote or the user asked.
- Ephemeral output (screenshots, debug logs) goes to gitignored `.ai/scratch/`,
diff --git a/.claude/skills/explain/SKILL.md b/.claude/skills/explain/SKILL.md
new file mode 100644
index 0000000000..45a283e161
--- /dev/null
+++ b/.claude/skills/explain/SKILL.md
@@ -0,0 +1,275 @@
+---
+name: explain
+description: Render a spec, plan, or research file from .ai/ as a self-contained HTML explainer saved beside it (same name, .html) — plain STE-80 prose, one SVG diagram of the whole change, before/after tabs, collapsible decisions and tasks — so a human understands it in minutes instead of reading the markdown. Use when asked to "explain this spec/plan", "make it readable", "visualize the plan", "make an HTML page for this", or after /spec-writing or /plan when someone must review the result. Do not use to design or change the content — the .md stays the source of truth (use /spec-writing or /plan) — and do not use for a pull request (use /pr-explainer).
+---
+
+# explain — turn a spec or plan into a page a human can understand fast
+
+Input: one markdown file in `.ai/specs/`, `.ai/plans/` or `.ai/research/`.
+Output: `{same path}.html` beside it — one self-contained file, committed with
+its source. The page explains the source. It never adds to it or replaces it:
+`/plan` and `/execute` keep reading the `.md`.
+
+The idea (from Andrej Karpathy): as agents write more of the work, humans spend
+more time understanding it. Three layers help, in order: controlled plain
+writing (STE-80), a diagram, and an interactive page. This skill produces all
+three in one file.
+
+**Announce at start:** "Using the explain skill — building the HTML explainer
+for {source path}."
+
+## Step 1: Resolve the source
+
+| Request | Source |
+|---------|--------|
+| A path is given | that file |
+| "the spec" / "this spec", no path | last-modified dated spec: `ls -t .ai/specs/2*.md \| head -1` |
+| "the plan", no path | last-modified dated plan: `ls -t .ai/plans/2*.md \| head -1` |
+| Two or more files match the user's words | ask which one — do not guess |
+
+Pick the template:
+
+| Source is under | Template |
+|-----------------|----------|
+| `.ai/plans/` | `.claude/skills/explain/assets/plan.html` |
+| `.ai/specs/` or `.ai/research/` | `.claude/skills/explain/assets/spec.html` |
+
+If the source is a spec with unchecked Open Questions (`- [ ]`), continue, but
+show them in a `.callout.warn` at the top of "Decisions". The page must not
+look final when the spec is not.
+
+## Step 2: Read the source, then the code it names
+
+1. Read the whole source file.
+2. Read `.claude/rules/writing-ste.md`. Every sentence you write follows it.
+3. Open each file, table or function that will appear anywhere on the page
+ (diagram, tasks, decisions, terms). Confirm it exists: `ls {path}` or
+ `grep -rn "{name}" {dir}`.
+
+🛑 Every fact on the page comes from the source or from code you opened. Do not
+add a fact to "complete the picture".
+
+When the source and the code differ, use this table:
+
+| The difference | Action |
+|----------------|--------|
+| The source describes the code BEFORE its change ("Cause", "Today", "Current behavior") | expected — explain it as the old behavior |
+| A path or line number in the source no longer exists (the code moved) | show the file name without the line number; list it under "source drift" in the Step 7 report |
+| The source's status does not match the code (says implemented but the code differs, or says draft but the code already has it) | do not choose one; explain the source, list it under "source drift" |
+| The source contradicts itself (a design section vs an acceptance criterion) | render both as written, add a `.callout.warn` naming the two sections, list it under "source drift" |
+| You cannot tell what the source means | STOP and ask the user |
+
+Never correct the source on the page. The user fixes the source; then the page
+is regenerated.
+
+## Step 3: Choose the one picture
+
+One diagram must explain the whole change. Choose it from this table — the
+first row that matches wins:
+
+| The source is mostly about… | Draw |
+|-----------------------------|------|
+| the source has a Mermaid overview diagram | the same picture in SVG: the same nodes, edges and changed (`hot` / `new`) marks — the spec author chose it |
+| a plan (any plan) | task graph: one column per dependency layer (the plan template has it) |
+| several independent fixes or changes (a bundle) | fix grid: one row per fix — fix name as `<text>` at x = 40, before box (`risk`) at x = 240, after box (`hot`) at x = 440, optional `small` note at x = 640; more than 6 fixes → a table instead of a figure |
+| a status or lifecycle | state diagram: one box per status, one edge per transition, label each edge with its trigger |
+| work that moves between people, modules or services | swimlanes: one lane per actor, boxes in time order left to right |
+| a changed calculation or behavior | before → after: two rows of boxes, the same steps, the changed box `hot` |
+| new or changed tables | entity boxes: table name + key columns, edges for foreign keys (the "Data model" figure) |
+| none of the above | a left-to-right flow of the main steps |
+
+Draw it with the SVG primitives already in the template (`.box`, `.box.hot`,
+`.box.new`, `.box.risk`, `.lane`, `.edge`, `.edge.hot`, the `#arrow` markers).
+Layout rules:
+
+- `viewBox` width is 800. Make the height fit the content. Only the task
+ graph may be wider (see the comment in `plan.html`).
+- Box 160×56 (task graph: 160×48). Columns at x = 40, 240, 440, 640 — at most
+ 4 boxes in a row, 40px apart. Rows 90px apart (task graph: 70px).
+- A label inside a 160px box is at most 18 characters. Put a longer detail in
+ a second `<text class="small">` line or in the caption.
+- At most 8 boxes in one figure. Two exceptions: the task graph (one box per
+ task) and the fix grid (two boxes per fix, at most 6 fixes).
+- Never put a color in the SVG. Use only the classes, so dark mode works.
+- Give each `<svg>` an `aria-label` that says what it shows in one sentence.
+- One main figure in "The picture". You may add ONE more figure only in the
+ "Data model" section (spec) or below the task graph (plan, for example the
+ shape of a new API). No third figure.
+
+## Step 4: Copy the template and stamp the source
+
+```bash
+SRC=.ai/specs/2026-10-04-example.md # the source from Step 1
+OUT="${SRC%.md}.html"
+cp .claude/skills/explain/assets/spec.html "$OUT" # plan.html for a plan
+git hash-object "$SRC"
+# Expected: a 40-character hex hash
+```
+
+Put `$SRC` in the `explain-source` meta, the kicker and the footer. Put the hash
+in the `explain-source-hash` meta. Step 6 and "Keeping pages fresh" compare
+that hash with the source to find a stale page.
+
+## Step 5: Fill every section
+
+Work top to bottom. Each `<!-- FILL: … -->` comment says what goes there.
+Delete the comment after you fill its section. Delete a whole `<section>` when
+the comment says it may be deleted and the source has nothing for it.
+
+Writing rules (from `.claude/rules/writing-ste.md`):
+
+- Rewrite, do not paste. A paragraph copied from the markdown is a failure.
+- Instructions ≤ 20 words. Facts ≤ 25 words. One idea per sentence.
+- Active voice: name the actor ("The route action saves the row").
+- Use the term the source uses, the same one every time.
+- Domain terms and code identifiers are allowed — put identifiers in `<code>`.
+
+Specs do not all use the template headings. Map each source section by its
+role. The names in brackets are the common alternatives.
+
+Spec template mapping:
+
+| Page section | From the source |
+|--------------|-----------------|
+| Kicker status | the source's Status line, verbatim ("Awaiting approval", "draft") |
+| TL;DR (3 sentences) | TLDR [Summary] + Problem Statement [Problem, Background] |
+| Scope | Goals / Non-goals [In scope / Out of scope]; delete when absent |
+| The picture | Step 3 |
+| The problem + Example | Problem Statement; the example uses synthetic numbers and names (Jane Doe, PART-001) |
+| How it works | Proposed Solution [Design, Approach], as numbered actions |
+| Before and after | the same scenario run through the old and the new behavior; for a bundle, one numbered item per fix in each tab |
+| Decisions | the Design Decisions table + resolved Open Questions; `human` tag for `**Answer:**`, `assumed` tag for `**Autonomous:**`, no tag when no question traces to the row |
+| Data model | Data Model Changes [Schema, Migrations]; delete when the source changes no schema |
+| Done when | Acceptance Criteria [Done when, Success criteria] |
+| Terms | every domain term a newcomer needs; copy the definition from `docs/content/src/glossary/terms.ts` when the term is there |
+
+Plan template mapping:
+
+| Page section | From the source |
+|--------------|-----------------|
+| Kicker branch / spec | the `**Branch:**` and `**Spec:**` lines; no line → delete the branch segment, write "none" for the spec |
+| Progress bar | count `- [x]` and `- [ ]` in the Progress list (else in the Steps checklist) |
+| Task graph | each task's `Depends on:` line; no such lines → list order, 4 per row, caption says so |
+| Tasks | one `<details class="task">` per task (or per Steps item); add `done` when its box is checked; delete the Files / Verify / Stop-if parts the source does not give |
+| Decisions | a Decisions / Notes section, if any; delete when absent |
+| Risks and stop points | every "STOP" / "If … turns out false" line |
+| Out of scope | every task's "Out of scope" line, without duplicates |
+
+Interactive parts — use only these three:
+
+1. **Tabs** (`[data-tabs]`) for before/after. The script is in the template.
+2. **`<details>`** for depth a first-time reader can skip.
+3. **A worked example calculator** — only when the source defines a formula
+ (a quantity, a price, a rounding rule). Add `<input type="number">` fields
+ prefilled with the source's example values and a few lines in the existing
+ `<script>` that recompute the result. No libraries.
+
+## Step 6: Check the page yourself
+
+Do every check below on `$OUT`. Do not hand any of them to the human. If a
+check fails, fix the page and do that check again.
+
+**1. Nothing left from the template.** Search the page:
+
+```bash
+grep -n "FILL" "$OUT"
+grep -nE '<(p|li|td|dd)( [^>]*)?>[[:space:]]*</(p|li|td|dd)>' "$OUT"
+# Expected: no output from either command
+```
+
+Then search for the sample text of the template you copied. Each line below must
+return nothing: "Sentence one.", "Step A", "Step B", "Feature name",
+"Imperative title", "newThing", "newTable", "path/to/file.ts", "<dt>Term</dt>",
+"Definition in one STE-80 sentence.", "YYYY-MM-DD-slug", "0 of 0 tasks".
+
+**2. The page is one self-contained file.**
+
+```bash
+grep -nE '<(script|link|img|iframe)[^>]*(src|href)="(https?:)?//' "$OUT"
+# Expected: no output
+```
+
+**3. Every SVG works in dark mode and has a label.**
+
+1. Read each `<svg>`. It uses only the template classes (`.box`, `.edge`, …).
+2. Make sure no `fill=`, `stroke=` or `style=` attribute holds a `#`, `rgb` or `hsl` color.
+3. Make sure each `<svg>` tag has a non-empty `aria-label`.
+4. Make sure no label is wider than its box and no edge crosses a box it does not connect to.
+
+**4. The HTML is well-formed.** Read the page from top to bottom once. Every
+`<section>`, `<details>`, `<div>`, `<ul>`, `<table>` and `<svg>` you opened
+has its closing tag, in the right order. Pay most attention to the sections you
+deleted or duplicated.
+
+**5. The page matches its source.**
+
+```bash
+git hash-object "$SRC"
+grep -o 'name="explain-source-hash" content="[^"]*"' "$OUT"
+# Expected: the same 40-character hash in both lines
+```
+
+**6. The prose is STE-80.** Do the STE-80 review pass
+(`.claude/rules/writing-ste.md` → Enforcement) on all page text. Skip code,
+the SVG and quoted template text. Check these 3 limits:
+
+1. Instruction sentences (plan tasks, verify steps): 20 words at most.
+2. Fact sentences: 25 words at most. A spec's "How it works" steps are facts.
+3. A rationale may go to 30 words.
+
+**7. Every fact is real.** For each fact on the page, point to the line in the
+source or the code you opened in Step 2. Delete a fact you cannot point to.
+
+Then give the user the path and this command to open the page:
+
+```bash
+open .ai/specs/2026-10-04-example.html
+```
+
+## Step 7: Report
+
+One short message: the page path, the diagram you chose and why (one line),
+and the "source drift" list from Step 2 (or "no source drift"). Commit only when the user asks, through
+`/check-and-commit`, with the `.html` and its source in the same commit.
+
+## Done when
+
+- [ ] `{source}.html` exists beside the source
+- [ ] Every check in Step 6 passes, done by you, not the human
+- [ ] The page has exactly one main diagram chosen by the Step 3 table
+- [ ] No fact on the page is missing from the source or the code
+
+## Keeping pages fresh
+
+The page records the hash of its source. When the source changes, the page is
+stale. To find every stale page, compare each page's recorded hash with its
+source:
+
+```bash
+for page in $(grep -rl 'name="explain-source"' .ai --include='*.html'); do
+ src=$(grep -o 'name="explain-source" content="[^"]*"' "$page" | sed 's/.*content="//; s/"$//')
+ rec=$(grep -o 'name="explain-source-hash" content="[^"]*"' "$page" | sed 's/.*content="//; s/"$//')
+ [ -f "$src" ] && [ "$(git hash-object "$src")" = "$rec" ] || echo "STALE $page"
+done
+# Expected: no output. Each STALE line names a page to regenerate.
+```
+
+For each stale page, run this skill again on its source. When a spec moves to
+`.ai/specs/implemented/`, move its `.html` too and update the source path in
+the meta, the kicker and the footer.
+
+## Failure → action
+
+| Symptom | Action |
+|---------|--------|
+| The source has neither a problem/design section (spec) nor a task or step list (plan) | STOP — tell the user which file you found and ask which one they meant |
+| The main diagram needs more than 8 boxes (not a task graph) | draw the top level only, and put the detail in `<details>` sections |
+| One Step 6 check fails twice after your fix | STOP — report the check and the section of the page it refers to |
+
+## Red flags — stop and re-read this skill
+
+- "I'll add a detail the spec forgot" — the page only explains; fix the source with /spec-writing.
+- "This paragraph is fine as it is, I'll paste it" — rewrite it in STE-80.
+- "A CDN chart library would be faster" — the page must work offline, as one file.
+- "Three diagrams show it better" — one main picture, plus at most one in the allowed places (Step 3).
+- "The code differs, so I'll describe the code" — explain the source and report the drift.
diff --git a/.claude/skills/explain/assets/plan.html b/.claude/skills/explain/assets/plan.html
new file mode 100644
index 0000000000..1cf98e7bb0
--- /dev/null
+++ b/.claude/skills/explain/assets/plan.html
@@ -0,0 +1,218 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<!-- FILL: source path and `git hash-object <source>` — the staleness check reads these two -->
+<meta name="explain-source" content=".ai/plans/YYYY-MM-DD-slug.md" />
+<meta name="explain-source-hash" content="0000000000000000000000000000000000000000" />
+<!-- FILL: the feature name + "plan" -->
+<title>Feature name plan</title>
+<style>
+ :root {
+ --bg: #fbfbf9; --panel: #ffffff; --ink: #262323; --faint: #6b6764;
+ --hairline: #e3e2de; --accent: #1e84b0; --accent-soft: #dff5ff;
+ --warn: #a3520f; --warn-soft: #fff1e0; --ok: #2c7a14; --ok-soft: #e4f8da;
+ --code-bg: #efefeb;
+ }
+ @media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #141416; --panel: #1c1c1f; --ink: #ececea; --faint: #a3a19c;
+ --hairline: #2e2e33; --accent: #5cc2ee; --accent-soft: #10303f;
+ --warn: #f0a35e; --warn-soft: #3a2614; --ok: #8fd672; --ok-soft: #1b3112;
+ --code-bg: #26262a;
+ }
+ }
+ * { box-sizing: border-box; }
+ body { margin: 0; background: var(--bg); color: var(--ink);
+ font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+ main { max-width: 880px; margin: 0 auto; padding: 48px 16px 96px; }
+ h1 { font-size: 30px; line-height: 1.2; margin: 8px 0 12px; }
+ h2 { font-size: 20px; margin: 56px 0 12px; padding-top: 24px; border-top: 1px solid var(--hairline); }
+ h3 { font-size: 16px; margin: 24px 0 8px; }
+ p, li { max-width: 72ch; }
+ a { color: var(--accent); }
+ code { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+ background: var(--code-bg); border-radius: 4px; padding: 1px 5px; }
+ .kicker { color: var(--faint); font-size: 13px; letter-spacing: .06em; text-transform: uppercase; }
+ .tldr { font-size: 18px; border-left: 3px solid var(--accent); padding: 4px 0 4px 16px; margin: 0; }
+ .callout { border-radius: 10px; padding: 12px 16px; margin: 16px 0; border: 1px solid var(--hairline); }
+ .callout.example { background: var(--accent-soft); }
+ .callout.warn { background: var(--warn-soft); }
+ .callout .label { display: block; font-size: 11px; font-weight: 700; letter-spacing: .08em;
+ text-transform: uppercase; color: var(--faint); margin-bottom: 4px; }
+ ol.steps { padding-left: 0; list-style: none; counter-reset: s; }
+ ol.steps li { counter-increment: s; position: relative; padding: 8px 0 8px 44px; }
+ ol.steps li::before { content: counter(s); position: absolute; left: 0; top: 8px; width: 28px; height: 28px;
+ border-radius: 50%; background: var(--accent-soft); color: var(--accent);
+ font-weight: 700; font-size: 14px; display: grid; place-items: center; }
+ figure { margin: 20px 0; background: var(--panel); border: 1px solid var(--hairline);
+ border-radius: 12px; padding: 16px; overflow-x: auto; }
+ figcaption { color: var(--faint); font-size: 14px; margin-top: 8px; }
+ /* SVG diagram primitives — use these classes, never inline colors */
+ svg.diagram { display: block; width: 100%; height: auto; min-width: 560px; }
+ svg .box { fill: var(--panel); stroke: var(--hairline); stroke-width: 1.5; }
+ svg .box.hot { stroke: var(--accent); stroke-width: 2.5; fill: var(--accent-soft); }
+ svg .box.new { stroke: var(--ok); stroke-width: 2; fill: var(--ok-soft); }
+ svg .box.risk { stroke: var(--warn); stroke-width: 2; fill: var(--warn-soft); }
+ svg .lane { fill: none; stroke: var(--hairline); stroke-dasharray: 4 4; }
+ svg .edge { fill: none; stroke: var(--faint); stroke-width: 1.5; }
+ svg .edge.hot { stroke: var(--accent); stroke-width: 2.5; }
+ svg text { fill: var(--ink); font: 14px ui-sans-serif, system-ui, sans-serif; }
+ svg text.small { fill: var(--faint); font-size: 12px; }
+ svg text.mono { font-family: ui-monospace, Menlo, monospace; font-size: 13px; }
+ svg marker path { fill: var(--faint); }
+ svg marker.hot path { fill: var(--accent); }
+ /* Tabs (before / after) */
+ .tabs { border: 1px solid var(--hairline); border-radius: 12px; background: var(--panel); margin: 16px 0; }
+ .tabs [role=tablist] { display: flex; gap: 4px; padding: 8px; border-bottom: 1px solid var(--hairline); }
+ .tabs button { font: inherit; font-size: 14px; border: 0; background: none; color: var(--faint);
+ padding: 6px 12px; border-radius: 8px; cursor: pointer; }
+ .tabs button[aria-selected=true] { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+ .tabs [role=tabpanel] { padding: 12px 16px; }
+ .tabs [role=tabpanel][hidden] { display: none; }
+ /* Decisions */
+ details { border: 1px solid var(--hairline); border-radius: 10px; background: var(--panel); margin: 8px 0; }
+ details > summary { cursor: pointer; padding: 10px 14px; list-style: none; }
+ details > summary::-webkit-details-marker { display: none; }
+ details > summary::before { content: "▸"; color: var(--faint); margin-right: 8px; display: inline-block; transition: transform .15s; }
+ details[open] > summary::before { transform: rotate(90deg); }
+ details > div { padding: 0 14px 12px 34px; }
+ .choice { font-weight: 600; }
+ .rejected { color: var(--faint); }
+ .tag { display: inline-block; font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;
+ border-radius: 999px; padding: 1px 8px; margin-left: 6px; vertical-align: 2px; }
+ .tag.human { background: var(--ok-soft); color: var(--ok); }
+ .tag.assumed { background: var(--warn-soft); color: var(--warn); }
+ table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
+ th, td { text-align: left; border-bottom: 1px solid var(--hairline); padding: 8px 10px; vertical-align: top; }
+ th { color: var(--faint); font-weight: 600; }
+ .table-wrap { overflow-x: auto; }
+ ul.checks { list-style: none; padding-left: 0; }
+ ul.checks li { padding: 6px 0 6px 28px; position: relative; }
+ ul.checks li::before { content: "☐"; position: absolute; left: 0; color: var(--accent); }
+ dl.terms dt { font-weight: 600; margin-top: 12px; }
+ dl.terms dd { margin: 2px 0 0 0; color: var(--faint); max-width: 72ch; }
+ footer { margin-top: 64px; color: var(--faint); font-size: 13px; border-top: 1px solid var(--hairline); padding-top: 16px; }
+ /* Plan-only */
+ .progress { height: 8px; background: var(--hairline); border-radius: 999px; overflow: hidden; margin: 12px 0 4px; }
+ .progress > span { display: block; height: 100%; background: var(--ok); }
+ .task .meta { color: var(--faint); font-size: 14px; }
+ .task.done > summary { color: var(--faint); text-decoration: line-through; }
+ .task pre { font: 13px/1.6 ui-monospace, Menlo, monospace; background: var(--code-bg); border-radius: 8px; padding: 10px 12px; overflow-x: auto; }
+</style>
+</head>
+<body>
+<main>
+
+ <header>
+ <!-- FILL: Plan · the plan's **Branch:** value (delete the segment if it has none) · date · source path -->
+ <p class="kicker">Plan · BRANCH-OR-none · 2026-01-01 · <code>.ai/plans/YYYY-MM-DD-slug.md</code></p>
+ <!-- FILL: the feature name -->
+ <h1>Feature name — implementation plan</h1>
+ <!-- FILL: goal — 2 STE-80 sentences: what exists when the plan is done, and how we prove it -->
+ <p class="tldr">Sentence one. Sentence two.</p>
+ <!-- FILL: done / total from the plan's Progress checklist (else its Steps checklist); width = done/total as a percent.
+ Spec: the plan's **Spec:** path, or the word "none". -->
+ <div class="progress"><span style="width: 0%"></span></div>
+ <p class="kicker">0 of 0 tasks done · spec: <code>SPEC-PATH-OR-none</code></p>
+ </header>
+
+ <section>
+ <h2>Task graph</h2>
+ <!-- FILL: one column per dependency layer (layer 0 = tasks with no dependencies).
+ Column x positions: 40, 240, 440, 640, then +200 per extra column (widen the viewBox
+ by 200 each time; the figure scrolls). Box 160×48, rows 70px apart.
+ No "Depends on:" lines in the plan → draw the tasks in list order, 4 per row, no
+ "Layer" labels, and say in the caption that the arrows show list order only.
+ Edges go from a task to the tasks that depend on it.
+ class "new" = done, "hot" = next task to run, "risk" = task with a STOP condition. -->
+ <figure>
+ <svg class="diagram" viewBox="0 0 800 200" role="img" aria-label="FILL: task dependency graph">
+ <defs>
+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>
+ </defs>
+ <text class="small" x="40" y="24">Layer 0</text>
+ <text class="small" x="240" y="24">Layer 1</text>
+ <rect class="box new" x="40" y="40" width="160" height="48" rx="8" />
+ <text x="120" y="69" text-anchor="middle">1 · Migration</text>
+ <path class="edge" d="M200,64 L238,64" marker-end="url(#arrow)" />
+ <rect class="box hot" x="240" y="40" width="160" height="48" rx="8" />
+ <text x="320" y="69" text-anchor="middle">2 · Types</text>
+ </svg>
+ <!-- FILL: one sentence on which tasks can run in parallel -->
+ <figcaption>Tasks in the same column can run in parallel.</figcaption>
+ </figure>
+ </section>
+
+ <section>
+ <h2>Tasks</h2>
+ <!-- FILL: one <details class="task"> per plan task, in order. Add class "done" when its
+ Progress box is checked. Summary = number + imperative title. Body = what it does
+ (1–2 STE-80 sentences), files, verify command + expected output, STOP condition.
+ Delete each sub-part (Files / Verify / Stop if) the source does not give — never
+ fill one in from the code. -->
+ <details class="task">
+ <summary><b>1.</b> Imperative title</summary>
+ <div>
+ <p class="meta">Depends on: none</p>
+ <p></p>
+ <p class="meta">Files</p>
+ <ul><li><code>path/to/file.ts</code> — what changes</li></ul>
+ <p class="meta">Verify</p>
+ <pre>command
+# Expected: output</pre>
+ <div class="callout warn"><span class="label">Stop if</span><p>The assumption that, if false, ends the task.</p></div>
+ </div>
+ </details>
+ </section>
+
+ <section>
+ <h2>Decisions</h2>
+ <!-- FILL: the plan's decisions, if it lists any (a Decisions / Notes section). Same shape
+ as the spec page: summary = question + choice, body = why. Delete if there are none. -->
+ <details>
+ <summary>Question? <span class="choice">Choice.</span></summary>
+ <div><p>Why: </p></div>
+ </details>
+ </section>
+
+ <section>
+ <h2>Risks and stop points</h2>
+ <!-- FILL: every STOP / escape-hatch line in the plan, as a table. Delete if there are none. -->
+ <div class="table-wrap">
+ <table>
+ <tr><th>Task</th><th>Stop if</th><th>Then</th></tr>
+ <tr><td></td><td></td><td></td></tr>
+ </table>
+ </div>
+ </section>
+
+ <section>
+ <h2>Out of scope</h2>
+ <!-- FILL: the union of every task's "Out of scope" line, deduplicated. Delete if there are none. -->
+ <ul><li></li></ul>
+ </section>
+
+ <footer>
+ <!-- FILL: source path -->
+ Generated by <code>/explain</code> from <code>.ai/plans/YYYY-MM-DD-slug.md</code>.
+ If this page and the source disagree, the source is correct.
+ </footer>
+
+</main>
+<script>
+ // Tabs: no dependencies. Works for every [data-tabs] block on the page.
+ document.querySelectorAll("[data-tabs]").forEach(function (root) {
+ var tabs = root.querySelectorAll("[role=tab]");
+ var panels = root.querySelectorAll("[role=tabpanel]");
+ tabs.forEach(function (tab, i) {
+ tab.addEventListener("click", function () {
+ tabs.forEach(function (t, j) { t.setAttribute("aria-selected", String(i === j)); });
+ panels.forEach(function (p, j) { p.hidden = i !== j; });
+ });
+ });
+ });
+</script>
+</body>
+</html>
diff --git a/.claude/skills/explain/assets/spec.html b/.claude/skills/explain/assets/spec.html
new file mode 100644
index 0000000000..b9fb76ab83
--- /dev/null
+++ b/.claude/skills/explain/assets/spec.html
@@ -0,0 +1,260 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<!-- FILL: source path and `git hash-object <source>` — the staleness check reads these two -->
+<meta name="explain-source" content=".ai/specs/YYYY-MM-DD-slug.md" />
+<meta name="explain-source-hash" content="0000000000000000000000000000000000000000" />
+<!-- FILL: the feature name, 2–5 words -->
+<title>Feature name</title>
+<style>
+ :root {
+ --bg: #fbfbf9; --panel: #ffffff; --ink: #262323; --faint: #6b6764;
+ --hairline: #e3e2de; --accent: #1e84b0; --accent-soft: #dff5ff;
+ --warn: #a3520f; --warn-soft: #fff1e0; --ok: #2c7a14; --ok-soft: #e4f8da;
+ --code-bg: #efefeb;
+ }
+ @media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #141416; --panel: #1c1c1f; --ink: #ececea; --faint: #a3a19c;
+ --hairline: #2e2e33; --accent: #5cc2ee; --accent-soft: #10303f;
+ --warn: #f0a35e; --warn-soft: #3a2614; --ok: #8fd672; --ok-soft: #1b3112;
+ --code-bg: #26262a;
+ }
+ }
+ * { box-sizing: border-box; }
+ body { margin: 0; background: var(--bg); color: var(--ink);
+ font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+ main { max-width: 880px; margin: 0 auto; padding: 48px 16px 96px; }
+ h1 { font-size: 30px; line-height: 1.2; margin: 8px 0 12px; }
+ h2 { font-size: 20px; margin: 56px 0 12px; padding-top: 24px; border-top: 1px solid var(--hairline); }
+ h3 { font-size: 16px; margin: 24px 0 8px; }
+ p, li { max-width: 72ch; }
+ a { color: var(--accent); }
+ code { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+ background: var(--code-bg); border-radius: 4px; padding: 1px 5px; }
+ .kicker { color: var(--faint); font-size: 13px; letter-spacing: .06em; text-transform: uppercase; }
+ .tldr { font-size: 18px; border-left: 3px solid var(--accent); padding: 4px 0 4px 16px; margin: 0; }
+ .callout { border-radius: 10px; padding: 12px 16px; margin: 16px 0; border: 1px solid var(--hairline); }
+ .callout.example { background: var(--accent-soft); }
+ .callout.warn { background: var(--warn-soft); }
+ .callout .label { display: block; font-size: 11px; font-weight: 700; letter-spacing: .08em;
+ text-transform: uppercase; color: var(--faint); margin-bottom: 4px; }
+ ol.steps { padding-left: 0; list-style: none; counter-reset: s; }
+ ol.steps li { counter-increment: s; position: relative; padding: 8px 0 8px 44px; }
+ ol.steps li::before { content: counter(s); position: absolute; left: 0; top: 8px; width: 28px; height: 28px;
+ border-radius: 50%; background: var(--accent-soft); color: var(--accent);
+ font-weight: 700; font-size: 14px; display: grid; place-items: center; }
+ figure { margin: 20px 0; background: var(--panel); border: 1px solid var(--hairline);
+ border-radius: 12px; padding: 16px; overflow-x: auto; }
+ figcaption { color: var(--faint); font-size: 14px; margin-top: 8px; }
+ /* SVG diagram primitives — use these classes, never inline colors */
+ svg.diagram { display: block; width: 100%; height: auto; min-width: 560px; }
+ svg .box { fill: var(--panel); stroke: var(--hairline); stroke-width: 1.5; }
+ svg .box.hot { stroke: var(--accent); stroke-width: 2.5; fill: var(--accent-soft); }
+ svg .box.new { stroke: var(--ok); stroke-width: 2; fill: var(--ok-soft); }
+ svg .box.risk { stroke: var(--warn); stroke-width: 2; fill: var(--warn-soft); }
+ svg .lane { fill: none; stroke: var(--hairline); stroke-dasharray: 4 4; }
+ svg .edge { fill: none; stroke: var(--faint); stroke-width: 1.5; }
+ svg .edge.hot { stroke: var(--accent); stroke-width: 2.5; }
+ svg text { fill: var(--ink); font: 14px ui-sans-serif, system-ui, sans-serif; }
+ svg text.small { fill: var(--faint); font-size: 12px; }
+ svg text.mono { font-family: ui-monospace, Menlo, monospace; font-size: 13px; }
+ svg marker path { fill: var(--faint); }
+ svg marker.hot path { fill: var(--accent); }
+ /* Tabs (before / after) */
+ .tabs { border: 1px solid var(--hairline); border-radius: 12px; background: var(--panel); margin: 16px 0; }
+ .tabs [role=tablist] { display: flex; gap: 4px; padding: 8px; border-bottom: 1px solid var(--hairline); }
+ .tabs button { font: inherit; font-size: 14px; border: 0; background: none; color: var(--faint);
+ padding: 6px 12px; border-radius: 8px; cursor: pointer; }
+ .tabs button[aria-selected=true] { background: var(--accent-soft); color: var(--accent); font-weight: 600; }
+ .tabs [role=tabpanel] { padding: 12px 16px; }
+ .tabs [role=tabpanel][hidden] { display: none; }
+ /* Decisions */
+ details { border: 1px solid var(--hairline); border-radius: 10px; background: var(--panel); margin: 8px 0; }
+ details > summary { cursor: pointer; padding: 10px 14px; list-style: none; }
+ details > summary::-webkit-details-marker { display: none; }
+ details > summary::before { content: "▸"; color: var(--faint); margin-right: 8px; display: inline-block; transition: transform .15s; }
+ details[open] > summary::before { transform: rotate(90deg); }
+ details > div { padding: 0 14px 12px 34px; }
+ .choice { font-weight: 600; }
+ .rejected { color: var(--faint); }
+ .tag { display: inline-block; font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;
+ border-radius: 999px; padding: 1px 8px; margin-left: 6px; vertical-align: 2px; }
+ .tag.human { background: var(--ok-soft); color: var(--ok); }
+ .tag.assumed { background: var(--warn-soft); color: var(--warn); }
+ table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
+ th, td { text-align: left; border-bottom: 1px solid var(--hairline); padding: 8px 10px; vertical-align: top; }
+ th { color: var(--faint); font-weight: 600; }
+ .table-wrap { overflow-x: auto; }
+ ul.checks { list-style: none; padding-left: 0; }
+ ul.checks li { padding: 6px 0 6px 28px; position: relative; }
+ ul.checks li::before { content: "☐"; position: absolute; left: 0; color: var(--accent); }
+ dl.terms dt { font-weight: 600; margin-top: 12px; }
+ dl.terms dd { margin: 2px 0 0 0; color: var(--faint); max-width: 72ch; }
+ footer { margin-top: 64px; color: var(--faint); font-size: 13px; border-top: 1px solid var(--hairline); padding-top: 16px; }
+</style>
+</head>
+<body>
+<main>
+
+ <header>
+ <!-- FILL: artifact kind · the source's own Status value, verbatim · date · source path -->
+ <p class="kicker">Spec · draft · 2026-01-01 · <code>.ai/specs/YYYY-MM-DD-slug.md</code></p>
+ <!-- FILL: the feature name -->
+ <h1>Feature name</h1>
+ <!-- FILL: TL;DR — exactly 3 STE-80 sentences: the problem, the change, the result for the user -->
+ <p class="tldr">Sentence one. Sentence two. Sentence three.</p>
+ </header>
+
+ <section>
+ <h2>The picture</h2>
+ <!-- FILL: the ONE diagram that explains the whole change (see SKILL.md Step 3 for which kind).
+ Copy the primitives below; move/duplicate them; delete what you don't use.
+ Coordinates: viewBox is 800 wide; boxes are 160×56; columns at x = 40, 240, 440, 640 (4 per row, 40px gaps).
+ Mark the changed parts with class "hot" (changed), "new" (added) or "risk". -->
+ <figure>
+ <svg class="diagram" viewBox="0 0 800 220" role="img" aria-label="FILL: one-sentence description of the diagram">
+ <defs>
+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>
+ <marker id="arrow-hot" class="hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>
+ </defs>
+ <!-- lane (optional: one per actor/module) -->
+ <rect class="lane" x="10" y="10" width="780" height="200" rx="10" />
+ <text class="small" x="24" y="32">Lane / actor name</text>
+ <!-- box -->
+ <rect class="box" x="40" y="80" width="160" height="56" rx="8" />
+ <text x="120" y="113" text-anchor="middle">Step A</text>
+ <!-- edge -->
+ <path class="edge" d="M200,108 L238,108" marker-end="url(#arrow)" />
+ <!-- changed box + hot edge -->
+ <rect class="box hot" x="240" y="80" width="160" height="56" rx="8" />
+ <text x="320" y="105" text-anchor="middle">Step B</text>
+ <text class="small" x="320" y="124" text-anchor="middle">what changed</text>
+ <path class="edge hot" d="M400,108 L438,108" marker-end="url(#arrow-hot)" />
+ <!-- new box -->
+ <rect class="box new" x="440" y="80" width="160" height="56" rx="8" />
+ <text class="mono" x="520" y="113" text-anchor="middle">newThing</text>
+ </svg>
+ <!-- FILL: one STE-80 sentence that tells the reader where to look first. Write your own;
+ the sample caption below is a placeholder; replace it. -->
+ <figcaption>Read left to right. The blue box is the part that changes.</figcaption>
+ </figure>
+ </section>
+
+ <section>
+ <h2>Scope</h2>
+ <!-- FILL: from the source's Goals / Non-goals (or In scope / Out of scope). Delete this
+ section if the source has neither. -->
+ <div class="table-wrap">
+ <table>
+ <tr><th>In scope</th><th>Out of scope</th></tr>
+ <tr><td></td><td></td></tr>
+ </table>
+ </div>
+ </section>
+
+ <section>
+ <h2>The problem</h2>
+ <!-- FILL: 2–4 STE-80 sentences: what happens today and why it is wrong -->
+ <p></p>
+ <div class="callout example">
+ <span class="label">Example</span>
+ <!-- FILL: one concrete case with real-looking (synthetic) numbers and names -->
+ <p></p>
+ </div>
+ </section>
+
+ <section>
+ <h2>How it works</h2>
+ <!-- FILL: the new behavior as a numbered sequence, one action per item, ≤20 words each -->
+ <ol class="steps">
+ <li></li>
+ </ol>
+ </section>
+
+ <section>
+ <h2>Before and after</h2>
+ <!-- FILL: the same scenario before and after. Delete this section if the spec adds
+ something new and nothing existed before. -->
+ <div class="tabs" data-tabs>
+ <div role="tablist">
+ <button role="tab" aria-selected="true">Before</button>
+ <button role="tab" aria-selected="false">After</button>
+ </div>
+ <div role="tabpanel"><p></p></div>
+ <div role="tabpanel" hidden><p></p></div>
+ </div>
+ </section>
+
+ <section>
+ <h2>Decisions</h2>
+ <!-- FILL: one <details> per row of the spec's Design Decisions table, most important first.
+ summary = the question, then the choice. Body = why (≤30 words) + rejected options.
+ Tag: "human" if an Open Question with **Answer:** settled it, "assumed" if **Autonomous:**
+ settled it, NO tag if no question traces to it. Delete the "Rejected:" line when the
+ source names no rejected option. -->
+ <details>
+ <summary>Question? <span class="choice">Choice.</span><span class="tag human">human</span></summary>
+ <div>
+ <p>Why: </p>
+ <p class="rejected">Rejected: option — reason.</p>
+ </div>
+ </details>
+ </section>
+
+ <section>
+ <h2>Data model</h2>
+ <!-- FILL: one box per table (header = table name, then key columns), edges = foreign keys.
+ Reuse the SVG primitives above. Delete this section if the spec changes no schema. -->
+ <figure>
+ <svg class="diagram" viewBox="0 0 800 160" role="img" aria-label="FILL: tables and their relations">
+ <rect class="box new" x="40" y="20" width="220" height="120" rx="8" />
+ <text class="mono" x="56" y="46">newTable</text>
+ <text class="small mono" x="56" y="72">id, companyId (PK)</text>
+ <text class="small mono" x="56" y="94">parentId → parent</text>
+ </svg>
+ </figure>
+ </section>
+
+ <section>
+ <h2>Done when</h2>
+ <!-- FILL: the spec's acceptance criteria, one per line, each testable -->
+ <ul class="checks">
+ <li></li>
+ </ul>
+ </section>
+
+ <section>
+ <h2>Terms</h2>
+ <!-- FILL: every domain term or identifier a newcomer would not know. When the term is in
+ docs/content/src/glossary/terms.ts, shorten its definition to one STE-80 sentence.
+ Otherwise define it only with words the source itself uses. -->
+ <dl class="terms">
+ <dt>Term</dt><dd>Definition in one STE-80 sentence.</dd>
+ </dl>
+ </section>
+
+ <footer>
+ <!-- FILL: source path -->
+ Generated by <code>/explain</code> from <code>.ai/specs/YYYY-MM-DD-slug.md</code>.
+ If this page and the source disagree, the source is correct.
+ </footer>
+
+</main>
+<script>
+ // Tabs: no dependencies. Works for every [data-tabs] block on the page.
+ document.querySelectorAll("[data-tabs]").forEach(function (root) {
+ var tabs = root.querySelectorAll("[role=tab]");
+ var panels = root.querySelectorAll("[role=tabpanel]");
+ tabs.forEach(function (tab, i) {
+ tab.addEventListener("click", function () {
+ tabs.forEach(function (t, j) { t.setAttribute("aria-selected", String(i === j)); });
+ panels.forEach(function (p, j) { p.hidden = i !== j; });
+ });
+ });
+ });
+</script>
+</body>
+</html>
diff --git a/.claude/skills/feature/SKILL.md b/.claude/skills/feature/SKILL.md
index 75e9efb21e..4202e78cd9 100644
--- a/.claude/skills/feature/SKILL.md
+++ b/.claude/skills/feature/SKILL.md
@@ -130,6 +130,18 @@ Start at the first selected phase whose artifact is missing or stale:
(and its changelog), re-gate (or re-record in autonomous mode), then resume.
- Skipping a phase is a logged decision, not a silent omission — it goes in the
run record with a reason.
+- Everything this pipeline writes is in STE-80 from the first draft: research,
+ spec, plan, the run record, and every phase hand-off message to the human.
+ STE-80 is the author's job. Never ask the human to check the style.
+- STE-80 is a gate at every phase transition, in both autonomous modes. Before
+ you announce the next phase, do the STE-80 review pass
+ (`.claude/rules/writing-ste.md` → Enforcement) on every research, spec or
+ plan file the phase wrote or changed. Log "STE-80 pass done" for each file
+ in the run record's Phase log.
+- Subagent results are raw material. Rewrite them in STE-80 before they go into
+ an artifact. After a subagent edits an artifact, do the review pass on it
+ yourself. Never accept the subagent's own "clean" claim
+ (`.claude/rules/writing-ste.md` → Enforcement).
## Alternative: the conductor
diff --git a/.claude/skills/grill/SKILL.md b/.claude/skills/grill/SKILL.md
index 97ee1f7c52..b8dee437d1 100644
--- a/.claude/skills/grill/SKILL.md
+++ b/.claude/skills/grill/SKILL.md
@@ -85,6 +85,9 @@ apply regardless of target:
chat
- [ ] Durable conventions reflected in `.claude/rules/`; glossary offers made
where the three-part test passed
+- [ ] Every resolution written to a spec or plan is in STE-80, and the
+ STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) is
+ done on that file
## Anti-patterns
diff --git a/.claude/skills/improve/SKILL.md b/.claude/skills/improve/SKILL.md
index 15b220ef7f..28806926b0 100644
--- a/.claude/skills/improve/SKILL.md
+++ b/.claude/skills/improve/SKILL.md
@@ -123,6 +123,8 @@ Write each plan **for the weakest plausible executor**:
Finish by writing `.ai/plans/improve/README.md` with the recommended execution order, dependencies, and a status column.
+Every plan and the README follow STE-80 (`.claude/rules/writing-ste.md`). Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) on each file before you present them.
+
## Invocation variants
- Bare invocation → full workflow above.
diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.md
index a29248bc48..d519fce0f1 100644
--- a/.claude/skills/plan/SKILL.md
+++ b/.claude/skills/plan/SKILL.md
@@ -70,6 +70,11 @@ Every task uses exactly this shape:
Hard rules for task content:
+- **Write every sentence in STE-80 from the first draft.** Use the write-time habits in `.claude/rules/writing-ste.md`. Never ask the human to check the style.
+- **Prose follows STE-80** (`.claude/rules/writing-ste.md`): one instruction
+ per step, imperative, at most 20 words. Step 5 makes the STE-80 review pass a gate.
+ Rewrite any subagent report in STE-80 before it goes into a task.
+
- **Migrations**: create with `pnpm db:migrate:new <name>` (never hand-pick a
timestamp; never `000000` as HHMMSS). SQL must use `id('prefix')` defaults,
`companyId` + composite PK `("id", "companyId")`, audit columns
@@ -122,6 +127,12 @@ file. Do not create a separate todo file.
## Step 5: Self-check, then present
+Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) first.
+Do it again after every later edit to the plan. If you corrected the spec
+while planning, do the pass on the spec too.
+
+- [ ] The STE-80 review pass is done for the plan (and for the spec if you
+ edited it), and every self-check box in the rule is ticked
- [ ] Every task has exact paths, exact commands, expected output
- [ ] Every migration task follows the hard rules above and is followed by a
`generate:types` step
@@ -130,5 +141,6 @@ file. Do not create a separate todo file.
- [ ] Every acceptance criterion in the spec is covered by at least one task,
and the final task is browser verification via `/test` for user-facing work
-Present the plan path and a one-paragraph summary. Wait for approval, then hand
-off to `/execute`.
+Present the plan path and a one-paragraph summary. Offer the reviewer view in
+one line: "Want an HTML explainer of this plan? (`/explain`)" — run it only on
+a yes. Wait for approval, then hand off to `/execute`.
diff --git a/.claude/skills/research/SKILL.md b/.claude/skills/research/SKILL.md
index 58da12bec8..c04a02fbe8 100644
--- a/.claude/skills/research/SKILL.md
+++ b/.claude/skills/research/SKILL.md
@@ -54,10 +54,19 @@ Rules:
- Be specific: `SAP S/4HANA inventory valuation methods`, not `SAP inventory`.
- Fan searches out to subagents (one competitor or one question per subagent) to
keep the main context clean. Each subagent returns findings + source URLs only.
+- End every subagent prompt with: "Write your report in STE-80
+ (`.claude/rules/writing-ste.md`): short sentences, active voice, no 'etc.'."
+ This makes the rewrite in Step 4 smaller. It does not replace that rewrite.
- Focus on data models, workflows, and terminology — not screenshots or UI copy.
## Step 4: Write the findings file
+> 🛑 Write every sentence in STE-80 from the first draft (`.claude/rules/writing-ste.md` → Write-time habits). Never ask the human to check the style.
+>
+> Subagent reports are raw material. Never paste one into the findings file
+> as it is. Rewrite each finding in STE-80 (`.claude/rules/writing-ste.md`)
+> before it goes in. Use one term per concept across all competitors.
+
Save to `.ai/research/{feature-slug}.md` (kebab-case slug). Use exactly this
structure:
@@ -91,6 +100,19 @@ One paragraph: what was researched, key findings.
- {URL}
```
+## Step 5: Do the STE-80 review pass
+
+Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) on
+`.ai/research/{feature-slug}.md`. Do it after the last subagent result is
+merged, and again after any later edit.
+
+1. Follow the 8 steps of the review pass in that rule, in order.
+2. Check every merged finding against its subagent report. A rewrite must not
+ turn a claim about one product into a claim about all products.
+3. Tick every box of the rule's self-check list.
+
+If a box still fails after 3 rewrite passes, STOP and report the failing lines.
+
## Done when
- [ ] Every matching domain row was researched, SAP included
@@ -98,6 +120,7 @@ One paragraph: what was researched, key findings.
unanswered — carry it into the spec's Open Questions)
- [ ] The findings file exists at `.ai/research/{slug}.md` with all sections filled
- [ ] Every claim has a source URL in the Sources section
+- [ ] The STE-80 review pass is done after the last edit, and every self-check box is ticked
## Next step
diff --git a/.claude/skills/spec-writing/SKILL.md b/.claude/skills/spec-writing/SKILL.md
index d3c30ec161..33c45aa83a 100644
--- a/.claude/skills/spec-writing/SKILL.md
+++ b/.claude/skills/spec-writing/SKILL.md
@@ -137,6 +137,15 @@ Only now. Copy `.ai/specs/template.md` to `.ai/specs/{YYYY-MM-DD}-{slug}.md`
(today's date, kebab-case slug) and fill every section, with the Step-5
resolutions baked into the design. Rules:
+- Write every sentence in STE-80 from the first draft (`.claude/rules/writing-ste.md` → Write-time habits). Never ask the human to check the style.
+- Prose follows STE-80 (`.claude/rules/writing-ste.md`): short sentences,
+ active voice, one term per concept. Tables over paragraphs for decisions.
+ Step 8 does the STE-80 review pass; the spec is not final until it passes.
+- Never paste research text or a subagent report into the spec as it is.
+ Rewrite it in STE-80 first.
+- The **Overview diagram** section holds exactly one Mermaid diagram that
+ explains the whole change (rules below). A Data Model section with new
+ tables may add a second one, an `erDiagram`. No other diagrams.
- SQL sketches use `id('prefix')`, `companyId`, composite PK, audit columns —
never `gen_random_uuid()`.
- Acceptance criteria must be testable: "user creates a PO with 3 lines and sees
@@ -146,6 +155,39 @@ resolutions baked into the design. Rules:
- The Open Questions section records the resolved Q&A (all boxes checked, each
with its inline answer) — it is the audit trail of Step 5, not a to-do list.
+### The overview diagram
+
+Choose the type with this table. The first row that matches wins.
+
+| The spec is mostly about… | Mermaid type |
+|---------------------------|--------------|
+| several independent fixes (a bundle) | `flowchart LR`, one `subgraph` per fix: old node → new node |
+| a status or lifecycle | `stateDiagram-v2`, one edge per transition, labelled with its trigger |
+| work that moves between people, modules or services | `sequenceDiagram`, one participant per actor |
+| a changed calculation or behavior | `flowchart LR`, two `subgraph`s named Before and After, the same steps in each |
+| new or changed tables only | `erDiagram` (precedent: `.ai/specs/implemented/2026-07-30-workflows-foundation.md`) |
+| none of the above | `flowchart LR` of the main steps |
+
+Syntax rules — nothing in this repo validates Mermaid, and a broken diagram
+only shows as an error in a preview. Keep to these:
+
+1. Put every node label in double quotes: `A["Pull from Inventory (old)"]`.
+ Parentheses, colons, slashes and `#` break unquoted labels.
+2. Node ids are plain letters and digits (`A`, `B2`, `oldPick`). No spaces,
+ no hyphens.
+3. Never write the word `end` as a node id or a bare label — it closes a
+ `subgraph`. Quote it: `E["end"]`.
+4. At most 12 nodes. A label is at most 30 characters.
+5. Mark what changes, do not color it: `:::hot` for a changed node, `:::new`
+ for an added node, with the two `classDef` lines from the template. Use no
+ other colors, so the diagram reads in light and dark themes.
+6. Put code identifiers in labels as plain text; backticks do not render.
+7. Every node and edge comes from the spec text or from code you opened. The
+ diagram adds no fact.
+
+Self-check before you continue: count the opening and closing lines of each
+`subgraph` (they must match), and confirm every edge names nodes that exist.
+
## Step 7: New questions discovered while writing
Writing the spec sometimes surfaces questions Step 4 missed. When that happens:
@@ -159,8 +201,21 @@ Writing the spec sometimes surfaces questions Step 4 missed. When that happens:
## Step 8: Finalize
After every question is resolved: add a changelog entry, set status per
-`.ai/specs/AGENTS.md`. The spec is now ready for `/plan` (or `/feature`, which
-calls it).
+`.ai/specs/AGENTS.md`.
+
+Then do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement).
+Do it again after every later edit, including edits from `/grill`, `/plan`
+corrections and subagent results.
+
+1. Follow the 8 steps of the review pass in that rule, in order.
+2. Tick every box of the rule's self-check list.
+
+If a box still fails after 3 rewrite passes, STOP and report the failing lines.
+
+The spec is now ready for `/plan` (or `/feature`, which calls it).
+
+Then offer the reviewer view in one line: "Want an HTML explainer of this
+spec? (`/explain`)". Run `/explain` only on a yes.
## Done when
@@ -170,8 +225,12 @@ calls it).
design reflecting the resolutions (no section contradicts an answer)
- [ ] Research file exists and is linked from the spec
- [ ] Every applicable heuristic (1–7) has a row in Design Decisions — no TBDs
+- [ ] The Overview diagram section has one Mermaid diagram, chosen from the
+ Step 6 table, that follows the syntax rules — not the template sample
- [ ] Any questions surfaced during writing (Step 7) were also resolved before
the spec was called final
+- [ ] The STE-80 review pass is done after the last edit, and every
+ self-check box is ticked
## Anti-patterns
diff --git a/AGENTS.md b/AGENTS.md
index 5b1c5ba757..6fde1c8971 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -146,7 +146,8 @@ IMPORTANT: Before any research or coding, match the task to this table. A single
| Creating/refreshing an AGENTS.md | `.claude/skills/create-agents-md/SKILL.md` |
| **Design Specs** | |
| Check existing specs before building | `.ai/specs/` + `.ai/specs/implemented/` |
-| Writing a new spec | `.claude/skills/spec-writing/SKILL.md` |
+| Writing a new spec | `.claude/skills/spec-writing/SKILL.md` + `.claude/rules/writing-ste.md` |
+| Explain a spec/plan as an HTML page (diagram + plain prose) | `.claude/skills/explain/SKILL.md` |
| **Workflows** | |
| Skills index — pipelines + all skills | `.claude/skills/README.md` |
| Competitor research for a feature | `.claude/skills/research/SKILL.md` |