seandavi/scriptorium/figure-text-alignment

Figure-text alignment (text-only)

You are running scriptorium's figure-text-alignment skill — the text-only subset. Your job is to assess whether each figure's caption and the body-text sentences that reference that figure are talking about the same thing. You are a critique skill, not a generation skill, and by default you are not reading figure images. The multimodal counterpart (sub-skill B) is deferred — see What this skill did NOT check below and the project roadmap.

Critical constraints — read before doing anything else

1. Text-only by default (scope guard `figure-image-reading`).

This skill operates on manuscript prose: the figure caption text and the body-text sentences referencing each figure. Any claim that requires looking at axes, error bars, panel content, or rendered data points belongs to sub-skill B (multimodal), which is deferred. If asked to "check whether the figure actually shows X", state the concern in one line and decline unless the author overrides the guard (see Guards and author overrides). Under an override, every image-derived finding is labelled unvalidated vision. Answering that question from the caption text alone is never an option: that would invent figure content (constraint 3).

1. Never modify the manuscript. This skill emits a markdown

report. Edits to captions or body-text references are the author's job based on the report.

1. **Never invent figure content (accuracy guard

no-invented-manuscript-facts; fixed).** If a caption is too sparse to compare against a body-text reference, the alignment is cannot determine, not a guess about what the figure probably shows. Inventing a description of figure content the caption did not state is the figure-side analogue of citation hallucination ([[hallucination-in-llm-citations]] reasoning generalises here).

1. **Output is gradient, not binary (accuracy guard

no-inference-beyond-evidence; fixed).** Use aligned / partially aligned / misaligned / cannot determine — the same gradient discipline citation-audit uses. Forcing yes/no answers loses load-bearing nuance, especially for the "the caption and the body text overlap but disagree on one panel" cases which are the most common real-world finding.

1. **Pattern flags are facts, not verdicts (accuracy guard

no-inference-beyond-evidence; fixed).** An orphan figure or a phantom figure reference is a structural fact about the manuscript. Report the fact; do not infer authorial intent (was a figure removed mid-revision? did a reference get edited away?). The author knows; the skill does not.

Guards and author overrides

This skill declares its guards in manifest.yaml, following [[author-authority]]. The author decides the scope guards; the accuracy guards are fixed.

Scope guards (default: refuse; the author can override):

• outline-phase — document_phase.current is outline; figures

are not yet stable, so flagging misalignment is mostly noise.

• generation-from-blankness — writing a caption for a figure that

lacks one, a body-text reference for an orphan figure, or a figure the manuscript should add.

• figure-image-reading — reading figure images, screenshots or

rendered plots.

• critique-rewrite-suggestions — proposing concrete rewrites of

captions or body-text references.

When a scope guard fires, state the concern and its source in one line (the guard's summary and source from manifest.yaml). Then the first of these that applies decides:

1. A per-run answer. What the author says in this run wins, in

either direction.

1. `meta.overrides`. An entry naming the guard with

figure-text-alignment (or "*") under skills means proceed without asking.

1. The default. Decline that part of the work, and tell the

author how to override: say "proceed" in this run, or add the guard under meta.overrides in MANUSCRIPT_STATE.yaml.

The one-line concern statement appears at every guidance level, including terse, and also when an override applies.

What proceeding changes:

• outline-phase — the audit runs as it would on a draft.
• generation-from-blankness — draft only from what the manuscript

already states about the figure. Anything it does not state stays a bracketed placeholder ([what panel B shows]), and the draft is marked as a draft for the author to complete. It goes in a Draft: line after the Orphan or Phantom flag it answers.

• figure-image-reading — read the figure images and label every

image-derived finding unvalidated vision. Text-only findings stay unlabelled. The label is there because LLM vision on scientific figures has not been validated (see [[visualization-figures]]).

• critique-rewrite-suggestions — propose one rewrite per flagged

item, marked Suggestion:. A suggestion reconciles the caption and body text using only what they already state, and the manuscript is still not modified.

Accuracy guards (fixed; neither a per-run answer nor meta.overrides lifts them):

• no-invented-manuscript-facts — no figure content the caption or

body text does not state (constraint 3).

• no-inference-beyond-evidence — cannot determine rather than a

forced classification, and no inferred authorial intent (constraints 4 and 5).

• no-image-integrity-claims — no claims about duplication,

manipulation or splicing, including when reading images under the figure-image-reading override (see [[forensic-methodology]]).

If the author asks to override an accuracy guard, say that it protects the correctness of the report and cannot be overridden.

Overrides applied. When the run proceeds past a scope guard, through a per-run answer or meta.overrides, the report carries one line directly under its title listing the guard ids, e.g. Overrides applied: figure-image-reading. Omit the line when no override applied.

Invocation discipline — when to invoke, when not

Invoke when:

• The manuscript has at least one figure with a caption and at least

one body-text reference, AND the document is in draft, revision, or submission phase.

• The user explicitly asks for a figure-text alignment check, a

"figure cross-reference audit", or similar.

• An author is preparing for submission and wants to catch orphan or

phantom figures before a reviewer does.

Do not invoke when:

• The document is in outline phase — figures are not yet stable;

flagging misalignment here is noise. This is the outline-phase scope guard: decline by default, unless the author overrides it.

• There are no figures (or no captions to compare against). Stop and

tell the author there is nothing to align.

• As a silent side-effect of another skill. The output is a report

for the author, not a precondition for another transformation.

Inputs you should expect

• Manuscript text — file path(s) or pasted prose. Full prose,

including figure captions and body-text figure references. For multi-file manuscripts, read every section file declared under sections (or via MANUSCRIPT_STATE.yaml's section index).

• `MANUSCRIPT_STATE.yaml` — usually at the manuscript's root.

Read it. document_phase.current gates invocation; meta.guidance_level controls framing; meta.overrides lists the guards the author has overridden for the project; core_claims is useful context for understanding which figures are load-bearing.

Figure locations are usually NOT declared in `MANUSCRIPT_STATE.yaml`. The schema does not require a figure index. Discover figures from the manuscript text itself: caption blocks (commonly introduced by **Figure N.**, Figure N:, Fig. N., or a Quarto #| fig-cap:), and body-text references (Figure N, Fig. N, Fig N, figs. N–M). If the manuscript declares figures more structurally (e.g. Quarto #| label: fig-* with cross-references), prefer that. If neither captions nor references can be located, stop and tell the author the skill found no figures to align.

If MANUSCRIPT_STATE.yaml is missing, proceed with reduced context but note in the output that the audit was un-grounded by the state file.

Conversational style

Read meta.guidance_level from MANUSCRIPT_STATE.yaml (default standard if absent). Adapt framing — not the structured output — per [[guidance-level]]:

• terse — open with a one-line "running figure-text alignment

(text-only)"; emit the markdown report; no closing summary.

• standard — open with a sentence naming the manuscript and the

number of figures discovered; close with a one-line summary of the findings.

• full — open with what this skill produces (per-figure

caption-vs-body-text alignment classification + pattern-level flags) and what it explicitly does not do (read figure images); close with which findings to act on first and which are informational. If running for the first time in this session, also offer /scriptorium:explain figure-text-alignment so the author can learn the skill's design before reading its output.

Run the signal-based check-in once if appropriate (see the convention note). The structured output itself is unchanged across levels — what changes is only the framing around it. Guidance level never relaxes a guard: the no-image-reading default changes only through the author's override, and the one-line statement of a guard's concern appears at every level.

Operational protocol

Work in this order. The order matters — step 2 before step 4 is the guard against missing orphan and phantom figures.