code-story · diff

git:20260819.75b2f19 to git:20260820.de181a7

8 added, 4 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: code-story
description: Build a wizard-style HTML page that teaches how and why a change works.
disable-model-invocation: true
---
- `/code-story <request>` — a PR, a diff, a branch, one commit — plus whatever the human says they do not understand.
+ `/code-story <request>` — a **change** (a PR, a diff, a branch, one commit) — plus whatever the human says they do not understand.
- A **code story** cuts a change into **chapters** and walks the reader through one at a time. A chapter answers one question, and its title *is* that question. It pulls hunks from whichever files hold that mechanism, so one chapter often spans several.
+ A **code story** re-cuts a change into the **stack of PRs** it could have been. One big diff lands whole; a stack arrives one reviewable step at a time, each standing on the last. Each **chapter** is one step in that stack: it answers one question, its title *is* that question, and it pulls out a **slice** of the change (hunks) from whichever files help answer it.
+ The stack is the narrative. Each chapter answers its question and hands the reader the next one, so order the chapters the way the understanding has to build.
+
A code story explains **why** the code changed the way it did. Write it for a day-one contributor — someone who knows nothing yet about this domain, this codebase, or its architecture.
- Tell it around code: each chapter is built from the lines it is about — changed, unchanged, or from a dependency — with a note pinning each claim to a line. Prose sets up the question and diagrams show shape; both are there to make those lines mean something.
+ Tell it around code: each chapter is built from the lines it is about — changed, unchanged, or from a dependency — with a note pinning each claim to a line. Everything else is there to make those lines mean something.
- One chapter per mechanism, not per file and not per commit — a two-file change with three ideas in it gets three chapters. Write in short, plain sentences: the reader is new here, so shorter beats fuller.
+ Choose whatever shows the change most clearly to someone seeing it for the first time, and reach for a picture before a paragraph every time one will carry the same meaning. A **call tree** shows what runs when you call something. A **call graph** or **dependency graph** shows what reaches what. A **sequence diagram** shows order across participants. A **file tree** shows where the change lands. A **behaviour table** shows one case as input, before, and after. Prose carries what none of them can.
+
+ One chapter per mechanism, not per file and not per commit — a two-file change with three ideas in it gets three chapters. Write in short, plain sentences: the reader is new here, so shorter beats fuller. Use Simplified Technical English, and adopt the role of a technical writer.
## Build it
1. **Read [`references/example.html`](references/example.html)** — a finished six-chapter story about a real 25-file PR. It is the specification: chapter size, how much diff one chapter shows, the voice of the notes, which changes earn a diagram, and how the files that earn no chapter get named and dismissed in a line each.
2. Read the change, and what explains it: the PR body, the linked issue, the review comments, the code before it, and the unchanged or third-party code the change leans on. Where the reasoning is nowhere to be found, the story says so rather than inventing one — and says so again at the end, in its own closing section naming where each *why* came from. Say plainly where you think the change is wrong; a reader who trusts a story that was quietly covering for the code loses the story too.
3. Copy [`references/template.html`](references/template.html) into the scratchpad and write the chapters into `<main>`, deleting its leading comment. The rail, chapter numbering, progress, note numbering, and the note↔code link all compute themselves — write `<article>` blocks and nothing else.
4. Publish with the Artifact tool, then hand over the link. Without that tool, write to the scratchpad and `open` the file. `template.html` already is the design, so publish it as it stands.