code-story
/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 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. Everything else is there to make those lines mean something.
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.