Narrative

Narrative Skill

Two jobs, in order of importance:

1. Revision protocol — how to absorb PI/user feedback without the report degrading back into a patchwork (most narrative damage happens during feedback rounds, not first drafts).
2. Article-type templates — positive examples of section logic per article type, consumed at outline time.

This skill is the delta on top of brain.md's <report_synthesis_protocol> (outline-first, claims-as-titles, lab-book test, anti-stacking pass). It does not repeat those rules — it adds what they lack: per-type section logic, the figure-narrative binding, and what to do when feedback arrives.

First draft (thin — most rules live in brain.md)

1. Pick the article type and record it as the first line of notes/report_outline.md: type: empirical | feasibility | comparison | policy-zh | survey. Surveys: stop here and follow skills/review/ + skills/survey-methodology/ instead — never both pipelines.
2. Read templates/<type>.md BEFORE writing the outline. The template gives the section logic for that type; your outline instantiates it with this project's claims. The lab-book test catches structure that mirrors the experiment DAG; the template shows what to write instead.
3. Read references/figure_narrative.md before commissioning figures. The outline must name its Figure 1 (schematic) and its hero figure (the one figure that settles the central claim) — both are outline-level decisions, not afterthoughts.

Revision protocol (core)

Every feedback batch that touches the report gets classified BEFORE any edit. Mixed batches: tag every item first, edit second (tag-all-before- edit-any) — append-only reviews/pi_feedback.md means earlier instructions never vanish, so there is no need to rush.

Add the class tag to each checklist line in notes/memory.md (the existing pi_correction_protocol checklist — same boxes, one tag + one-line rationale extra):

Copy code
- [ ] <instruction verbatim>  [class: local-fix | section-rewrite | restructure — <one-line why>]

Class 1 — local-fix (a number, a wording, a citation)

The pi_correction_protocol order applies unchanged: ledger first, report second. Then:

• grep report.tex for OTHER occurrences of the corrected number (abstract, captions, tables — printed values drift in packs, not alone).
• re-read the first sentence of the touched paragraph against its section's outline thesis (10 seconds — does the paragraph still serve the claim?).
• the outline is NOT touched — unless the corrected number appears in, or defines, the central-claim sentence (e.g. a threshold comparison like "99.987% < 99.99%"). Then this is not a local-fix; reclassify as restructure and follow that flow.

Class 2 — section-rewrite (a section's argument is wrong/weak)

Precondition: if the feedback strikes an L2 claim, the experiment re-spawn (ledger fix) comes FIRST; this class begins only after notes/experiments.md § L2.X reflects the new physics.

1. Edit that section's block in notes/report_outline.md first (thesis / evidence / synthesis move).
2. Rewrite the section from outline + ledger — single-section scope (mv the old text into the editor's view, don't patch sentence by sentence around a broken spine).
3. Check the transitions: the last paragraph of the previous section and the first of the next still hand over correctly.

Class 3 — restructure (the central claim changes)

Default triggers — burden of proof is reversed. Any of:

• feedback strikes a headline finding (an L2 claim quoted in the abstract),
• feedback contradicts a sentence of the abstract,
• experiments are added or removed after the report exists.

→ classify as restructure BY DEFAULT. Downgrading to a smaller class requires a one-line written justification on the checklist line.

Flow:

1. Re-derive the WHOLE outline (new central claim, possibly new type template consultation). Diff old vs new outline.
2. Walk report.tex section by section against the new outline — rewrite what the diff touches, keep what it doesn't.
3. Figure re-audit: does the hero figure still settle the NEW central claim? If not, commission a replacement — and the illustrator_write spawn task must quote the NEW claim text (spawn prompts are frozen snapshots; re-spawning with the old task resurrects the old framing).
4. Re-verify every already-ticked checkbox in notes/memory.md PI sections. Prose-level feedback ("stop calling it deterministic") lives only in report.tex — a rewrite can silently resurrect what an earlier round corrected. Each previously-ticked box gets re-checked against the new text; re-tick or re-fix.

Pre-finish reconciliation

Before finish() (and before the final PI review that the finish gate requires): one outline-vs-tex walkthrough — for each section, first paragraph vs outline thesis. Attach the outline verbatim to the final request_pi_review so PI reviews the argument, not just the prose.

Number provenance (interaction with correctness gates)

Rewrites must not orphan numbers. Every quantitative value in report.tex traces to a results.json computed.* field plus a stated transform (rounding, unit change). After a restructure, sweep the rewritten sections for numbers with no surviving source — flag, don't guess. Char-for-char identity is NOT required (rounding and Chinese prose legitimately reformat); traceability is.