# Plan-review authoring notes

Accumulated from review rounds on QUE-344 (2026-08-11). Apply to every plan-review
document authored in this repo, before first render. These extend the standing
style rules (plain prose, no coined vernacular, takeaway first).

## 1. Mechanical structure, no narrative

A section describes a mechanism as: selection/trigger, then stages in order,
then what each stage produces, then what does not change. No scene-setting, no
"the track exists to...", no framing sentences. A table for a mapping
(input kind → output) beats prose.

## 2. Explain a format before using its vocabulary

Never name an internal data-shape detail (key names, offsets, "codepoint
ranges", "grounding") without first saying what the thing is in plain words.
Pattern: state what the format IS ("the response stores all the text in one
long string; each tree node points at the stretch that belongs to it"), and
the operations on it become obvious. Every mechanism must relate to the end
goal — reading a financial document — not to data-shape trivia.
Flagged live: "a node's text is the top-level markdown sliced at the node's
codepoint range" — "sounds like a spell being invoked."

## 3. No inverted sentences — contents first, contrast second

Do not structure a sentence to withhold the payload for suspense. Flagged
live: "they keep what the graft doesn't take: ..." — the reader is shaken out
of the explanation waiting for the colon to resolve. State directly what the
thing contains ("A figure record stores the kind of figure, the description,
the rectangle, the value table..."), then, if useful, the contrast ("the
projection passes the graft only text, id, and rectangle").

Same family: "What the two paths share sits outside them" — say "The paths
share two things: nomination upstream, the graft downstream."

## 4. One decision per section, decision points labeled

A reviewer approves sections independently. Anything genuinely open is
labeled "Decision point for review:" with the concrete choice stated, not an
open-ended question.

## 5. Evidence stays quantified and self-contained

Cite counts and pages ("seven labels against eight values", "318 saved page
scans") rather than adjectives, and describe a referenced defect by what
happened, never by a session-internal label ("the page-31 class").