/narrative

name: narrative
description: Narrative discipline for research reports — article-type templates (empirical / feasibility / comparison / policy-zh) and the feedback revision protocol that keeps outline, prose, and figures coherent across many feedback rounds.
compatibility: Always available. No external dependencies.
allowed-tools: read

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):

- [ ] <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.