Choose pr-explain diagrams by what the reader would otherwise have to work out #160

New issue

Closed

opened 2026-08-28 05:08:50 +01:00 by vnprc-agent · 1 comment

vnprc-agent commented

2026-08-28 05:08:50 +01:00

Contributor

Make the pr-explain section pass choose diagrams by what a reader would otherwise have to work out, so a report carries a few figures that earn their place instead of a figure per section.

Primary goals:

A generative gate, not a prohibition — the agent states the reader's question and what the picture makes visible before it picks any markup, and writing prose instead is a stated correct outcome.
Component chosen by the relationship — each component's spatial promise is named, so a set of grouped facts stops being rendered as parallel lanes.
Figures stop introducing vocabulary — every label uses words the surrounding prose has already used, in the reader's terms rather than in codes.
Figures planned at outline time — the outline names which relationships are worth drawing, instead of each section pass deciding alone under pressure to produce one.

Current state and specifics

section-prompt.md:27 reads "Use more pictures or animated state diagrams when they materially reduce cognitive work, not decoration." The qualifier is there, but the instruction is a quota and it is being met. outline-prompt.md does not mention figures at all, so every figure is an in-the-moment decision by a section pass that cannot see the report as a whole.

section-prompt.md:24 lists the available components as an inventory — "flows, lanes, comparisons, codewalks, timelines" — without saying which relationship each one encodes. Nothing tells the agent that rx-lanes means "these columns correspond row by row", which is what component-gallery.html:1301 says in its own heading: "Aligned lanes compare work at the same stage."

An observed failure from a generated report: two rx-lane sections, each an ol.rx-flow with data-steps="3", used to present two groups of unordered facts about file ownership and permissions. The lanes had no stages, so row 2 of one column had nothing to do with row 2 of the other; both were padded to three entries because data-align="columns" requires equal counts; the ordered-list markup asserted a sequence that did not exist; the labels introduced numeric permission codes the report never defined; and the paragraph immediately below the figure stated the same thing in prose, better, because it also gave the reason. The format drove the content.

What to add

Lead with the question the agent must answer before choosing markup, drawn from Larkin and Simon's account of why diagrams sometimes help (locality, reduced search, and perceptual inference — text is sequential, a diagram is indexed by location): what would the reader have to work out from the prose, that the picture would let them see? If the answer is "nothing, the prose states it directly," there is no figure, and that is a normal outcome rather than a failure.

A corollary worth stating explicitly, because it inverts the current default: language is already sequential, so a sequence is the relationship prose handles best, which makes rx-flow structurally the lowest-value component and the one reached for first. Diagrams earn the most on relationships prose holds poorly — containment, correspondence, divergence, and anchoring to a location in code.

Then name each component's spatial promise so the choice is checkable:

Component	Promise	Fails when
`rx-flow`, `rx-sequence`	steps are ordered	reordering them would not make it false
`rx-lanes`	row N of every lane is the same stage	the lanes are independent lists
`rx-branch`	arms are exclusive outcomes of one test	the arms are not exclusive, or there is no test
`rx-compare`	a complete grid, same attributes for every subject	subjects have different attributes, or cells are empty
`rx-timeline`	chronology	order is not time
`rx-codewalk`	annotations anchored to specific lines	the code is illustrative rather than the subject

Row order is deliberately not a channel for rx-compare: sorting a table does not change what it says, so a reorder check must not be applied to it.

Finally, a vocabulary rule with a basis in the split-attention effect: a figure that forces the reader to import knowledge from outside it adds load rather than removing it, so a figure may not be the first place a term appears, and labels state meaning rather than codes.

Scope

In scope: section-prompt.md (replace the quota line, add the gate, the promise table, and the vocabulary rule) and outline-prompt.md (plan figures per section, including planning none). Prompt text only.

Tracked elsewhere: mechanical enforcement in the report validator — flagging bare permission codes or other undefined tokens in figure labels, and a caption that closely duplicates its neighbouring paragraph — which needs its own issue against the validator once the Go port in allod/tools#142 settles.

Make the pr-explain section pass choose diagrams by what a reader would otherwise have to work out, so a report carries a few figures that earn their place instead of a figure per section. Primary goals: - **A generative gate, not a prohibition** — the agent states the reader's question and what the picture makes visible before it picks any markup, and writing prose instead is a stated correct outcome. - **Component chosen by the relationship** — each component's spatial promise is named, so a set of grouped facts stops being rendered as parallel lanes. - **Figures stop introducing vocabulary** — every label uses words the surrounding prose has already used, in the reader's terms rather than in codes. - **Figures planned at outline time** — the outline names which relationships are worth drawing, instead of each section pass deciding alone under pressure to produce one. ### Current state and specifics `section-prompt.md:27` reads "Use more pictures or animated state diagrams when they materially reduce cognitive work, not decoration." The qualifier is there, but the instruction is a quota and it is being met. `outline-prompt.md` does not mention figures at all, so every figure is an in-the-moment decision by a section pass that cannot see the report as a whole. `section-prompt.md:24` lists the available components as an inventory — "flows, lanes, comparisons, codewalks, timelines" — without saying which relationship each one encodes. Nothing tells the agent that `rx-lanes` means "these columns correspond row by row", which is what `component-gallery.html:1301` says in its own heading: "Aligned lanes compare work at the same stage." An observed failure from a generated report: two `rx-lane` sections, each an `ol.rx-flow` with `data-steps="3"`, used to present two groups of unordered facts about file ownership and permissions. The lanes had no stages, so row 2 of one column had nothing to do with row 2 of the other; both were padded to three entries because `data-align="columns"` requires equal counts; the ordered-list markup asserted a sequence that did not exist; the labels introduced numeric permission codes the report never defined; and the paragraph immediately below the figure stated the same thing in prose, better, because it also gave the reason. The format drove the content. ### What to add Lead with the question the agent must answer before choosing markup, drawn from Larkin and Simon's account of why diagrams sometimes help (locality, reduced search, and perceptual inference — text is sequential, a diagram is indexed by location): **what would the reader have to work out from the prose, that the picture would let them see?** If the answer is "nothing, the prose states it directly," there is no figure, and that is a normal outcome rather than a failure. A corollary worth stating explicitly, because it inverts the current default: language is already sequential, so a sequence is the relationship prose handles best, which makes `rx-flow` structurally the lowest-value component and the one reached for first. Diagrams earn the most on relationships prose holds poorly — containment, correspondence, divergence, and anchoring to a location in code. Then name each component's spatial promise so the choice is checkable: | Component | Promise | Fails when | | --- | --- | --- | | `rx-flow`, `rx-sequence` | steps are ordered | reordering them would not make it false | | `rx-lanes` | row N of every lane is the same stage | the lanes are independent lists | | `rx-branch` | arms are exclusive outcomes of one test | the arms are not exclusive, or there is no test | | `rx-compare` | a complete grid, same attributes for every subject | subjects have different attributes, or cells are empty | | `rx-timeline` | chronology | order is not time | | `rx-codewalk` | annotations anchored to specific lines | the code is illustrative rather than the subject | Row order is deliberately not a channel for `rx-compare`: sorting a table does not change what it says, so a reorder check must not be applied to it. Finally, a vocabulary rule with a basis in the split-attention effect: a figure that forces the reader to import knowledge from outside it adds load rather than removing it, so a figure may not be the first place a term appears, and labels state meaning rather than codes. ### Scope In scope: `section-prompt.md` (replace the quota line, add the gate, the promise table, and the vocabulary rule) and `outline-prompt.md` (plan figures per section, including planning none). Prompt text only. Tracked elsewhere: mechanical enforcement in the report validator — flagging bare permission codes or other undefined tokens in figure labels, and a caption that closely duplicates its neighbouring paragraph — which needs its own issue against the validator once the Go port in allod/tools#142 settles.