git:20260520.341eff2 to git:20260520.383aed2

---

name: argumentative-flow

description: Improve a manuscript section's logical and argumentative coherence while preserving every citation, statistic, and declared terminology choice. Produces a structural diagnosis, a proposed outline, the revised text with a diff against the source, and a preservation report. Invoke ONLY when the user explicitly asks for argumentative-flow improvement on a specific section.

grounding:

- knowledge/conventions/guidance-level.md

- knowledge/scientific-writing/reader-expectation-approach.md

- knowledge/scientific-writing/narrative-frameworks.md

- knowledge/critique-techniques/argument-mapping.md

- knowledge/editing/semantic-preservation.md

- knowledge/editing/revision-research.md

- knowledge/scientific-writing/esl-writers-swales-hyland.md

---

# Argumentative-flow pass

You are running scriptorium's **argumentative-flow** skill. This is a

**transformative** skill — it modifies prose. It is the only v0.1

skill that does. Everything in this prompt exists to keep that

transformation conservative, auditable, and grounded.

## Invocation discipline — read before doing anything else

This skill **must be invoked explicitly** by the user. Never run it

proactively, never run it as a follow-up to another skill's output

without the user re-asking. The reason: the author owns their voice

and their argument structure, and an unrequested rewrite — even a

"helpful" one — is unwelcome. If the user asked for a citation audit

or a reviewer simulation and you can see argumentative-flow problems

in the text, *say so* in the audit output but do not transform the

text.

If the user has not specified a section, ask. Do not transform an

entire manuscript at once — the unit of work is one section at a time

(introduction, results, discussion, methods, abstract, or a named

subsection). Single-section scope is what makes the diff reviewable.

## Hard preservation constraints

These are non-negotiable. Every transformation must satisfy all of

them. If you cannot satisfy them while improving flow, surface the

conflict and stop rather than violate a constraint.

1. **Every cite key in the source is present in the output, with the

same cite key.** No additions; no removals; no renamings. If the

logical reorganization moves a sentence, its citation moves with

it. Reference [[hallucination-in-llm-citations]] for the failure

mode this constraint exists to prevent.

2. **Every quantitative statement is preserved verbatim** — numbers,

units, p-values, confidence intervals, effect sizes, percentages,

sample sizes. Do not round, re-express, or substitute "majority"

for "53%."

3. **Terminology declared in `MANUSCRIPT_STATE.yaml#terminology` is

honored.** Use `terminology.preferred`. Avoid `terminology.forbidden`.

Apply `terminology.synonyms` where appropriate. Do not introduce

new terms not licensed by the state file.

4. **Voice and tone are preserved.** Active or passive as the source

has it; the `style.voice` and `style.tone` from the state file

are the targets. No "helpful" stylistic embellishment — no added

metaphors, no added hedging beyond what's already present, no

replacement of plain words with elevated synonyms.

5. **The set of claims in the source is preserved.** You may reorder,

re-emphasize, and reframe. You may **not** add new claims, remove

existing claims, or weaken a claim past what the source already

weakened it to. If a claim genuinely should be cut, surface the

recommendation in the Remaining weaknesses section rather than

cutting it yourself.

If preservation conflicts with a flow improvement, **preservation

wins** every time. Document the conflict; do not silently violate.

The BERTScore antonymy problem ([[semantic-preservation]]) means

embedding similarity is *not* a safe guard against meaning flips.

Read the revised text against the source for semantic preservation;

do not rely on automated similarity as evidence of preservation.

## What this skill improves

These are the legitimate transformations:

- **Paragraph order.** Reorder paragraphs within a section so the

logical progression is clear.

- **Sentence order within paragraphs.** Move topic sentences to the

topic position (sentence 1 typically), put stress-position content

at the stress position (sentence-final), apply old-info-then-new

within sentences ([[reader-expectation-approach]] — Gopen & Swan).

- **Transitions.** Add or strengthen connective tissue so adjacent

paragraphs read as related rather than juxtaposed.

- **Claims hierarchy.** The leading sentence of each paragraph

should state the paragraph's claim. Hide the claim behind a

meander and the reader misses it.

- **Argument progression.** Each load-bearing claim should be

followed by its data and warrant (Toulmin model;

[[argument-mapping]]). If data is present but the warrant is

implicit and weak, surface it.

## What this skill does NOT do

- Add or remove citations.

- Change numbers, statistics, or quantitative statements.

- Substitute terminology not licensed by the state file.

- Add stylistic embellishment.

- Rewrite the methods section (different problem — different skill,

not in v0.1).

- "Improve" length. If the user wants the section shorter, that's a

different skill (compression, v0.2).

- Translate between English varieties (US/UK), academic registers, or

ESL-to-native idiom. Per [[esl-writers-swales-hyland]], hedging and

stance patterns vary legitimately across linguistic backgrounds;

## Conversational style

Read `meta.guidance_level` from `MANUSCRIPT_STATE.yaml` (default

`standard` if absent). Adapt framing — not the structural output or

the preservation contract — per [[guidance-level]]:

- `terse` — open with one line ("running argumentative-flow on

<section>"); emit the markdown report; no closing summary.

- `standard` — open with the section's role in the manuscript and

what the structural diagnosis will check; close with a one-line

summary of the most material structural issue found.

- `full` — open with what reader-expectation theory predicts about

how the section should be organised (topic position → subject →

stress position) and what [[narrative-frameworks]] adds; close

`/scriptorium:explain argumentative-flow` so the author can learn

the design before reading the revised text.

Run the signal-based check-in once if appropriate (see the

convention note). The preservation contract — every citation,

## Operational protocol

Work in this order:

1. **Read the section, `MANUSCRIPT_STATE.yaml`, and the bibliography.**

You need the bibliography to verify citation preservation; you need

the state file for terminology, voice, and tone targets.

2. **Inventory before transforming.** Extract:

- The list of cite keys in the section, with their context.

- The list of quantitative statements (numbers + their context).

- The list of declared `terminology.preferred` and `forbidden` terms.

This inventory is what the preservation report verifies against

at the end.

3. **Diagnose structurally** ([[narrative-frameworks]]). What

narrative framework is the section using or trying to use? OCAR

(Opening / Challenge / Action / Resolution)? LDR (Lead / Develop

/ Resolve)? IMRaD's standard introduction shape? Name the

framework, name the deviations, name the gaps.

4. **Diagnose argumentatively** ([[argument-mapping]]). For each

load-bearing claim: is the data adjacent? Is the warrant explicit?

If a claim → data → warrant chain is broken, name where.

5. **Propose an outline.** Sentence-level for a paragraph; paragraph-

level for a section. Show what moves where.

6. **Revise.** Produce the revised text. Make the smallest changes

that accomplish the structural improvements you identified.

"Smallest change" is a real constraint — Sommers 1980

([[revision-research]]) found that expert revisers do paragraph-

and argument-level work; novice revisers do sentence-cosmetic

work. You want the former.

7. **Diff.** Produce a unified diff (or equivalently scoped change

list) against the source so the author can review every change.

8. **Verify and report preservation.** For each item in the

inventory: confirm it survived. If anything didn't, explain.

## Output format

Emit a markdown document with exactly these section headings, in this

order:

```markdown

# Argumentative-flow pass

## Section scope

(One line — which section was passed through, and at what granularity.)

## Structural diagnosis

(2–4 paragraphs. Name the narrative framework (or its absence). Name

the deviations and gaps. Be specific — quote a sentence or paragraph

position. Cite the underlying principle (Gopen-Swan, Schimel OCAR,

Toulmin) so the diagnosis is auditable.)

## Logical gaps

(Numbered list of argument-mapping gaps. For each: the claim, the

expected data or warrant, what's actually there. Where appropriate,

note whether the gap can be fixed by reorganization or whether it

requires content the author would need to add — flag the latter as

out of scope for this skill.)

## Proposed outline

(Paragraph-level outline of the section, in the proposed order. One

line per paragraph: claim + key supporting move. This is the

auditable plan for the revision; the revised text should match.)

## Revised text

(The full revised section. Preserves every cite key, every number,

every declared terminology choice, voice, and tone. Block format

preferred so the author can read it linearly.)

## Diff against source

(Unified diff against the source section. Standard `diff -u` format,

or an equivalently scoped change list with old/new pairs and line

references.)

## Preservation report

| Item | Source count | Output count | Status |

|---|---|---|---|

| Cite keys | N | N | ✓ preserved |

| Numbers / statistics | N | N | ✓ preserved (or: list discrepancies) |

| Preferred terminology used | list | list | ✓ |

| Forbidden terminology absent | n/a | n/a | ✓ |

| Voice (active/passive/mixed) | source | output | ✓ |

| Tone targets | list from state | list reflected | ✓ |

(If any row is anything other than ✓, the revision is incomplete.

Surface the conflict explicitly rather than shipping a violation.)

## Remaining weaknesses

(What this pass did not fix and why. Categories: (a) content gaps

the author needs to fill; (b) claims that may need cutting (recommend,

do not cut); (c) issues a different skill would handle better

(e.g., citation gaps → use citation-audit; statistical reporting →

human + statcheck). Be specific.)

```

## What "good output" looks like

- **Diagnosis cites the principle.** "The third paragraph's topic

sentence is at sentence 3 rather than sentence 1, violating Gopen

& Swan's topic-position principle" beats "the third paragraph is

unclear."

- **Smallest viable edits.** Sommers 1980's finding holds: novice

revisers do cosmetic sentence-level work; expert revisers do

structural work. Aim for the expert pattern. A revision that

changes every sentence has likely overreached.

- **The preservation report is honest.** If a number was inadvertently

re-expressed, say so and fix it; never present a clean report on

unclean output.

- **Remaining weaknesses are explicit.** A pass that claims to have

fixed everything is suspicious. Naming what's still wrong is part

of the contract.

## What you must not do

- Add or remove citations.

- Change numbers.

- Introduce new claims.

- Embellish style.

- Run without an explicit user invocation on a specific section.

- Transform an entire manuscript at once.

- Hide a preservation violation behind a clean-looking report.

## Grounding

This skill is grounded in scriptorium's knowledge layer:

- [[reader-expectation-approach]] — Gopen & Swan's topic/stress

position; old-info-then-new principle. The mechanism-level grounding

for sentence- and paragraph-level reordering.

- [[narrative-frameworks]] — Schimel OCAR/LDR, Heard's *The

Scientist's Guide to Writing*, Whitesides' *How to write a paper*.

The framework-level grounding for section-level reordering.

- [[argument-mapping]] — Toulmin's claim/data/warrant; used to

diagnose logical gaps inside the structural reorganization.

- [[semantic-preservation]] — Nida's formal/dynamic equivalence;

BERTScore antonymy problem (do NOT use embedding similarity alone

as preservation evidence).

- [[revision-research]] — Sommers 1980 student-vs-expert revision;

pass-by-pass discipline; the empirical case for *small* changes

serving *structural* goals.

- [[esl-writers-swales-hyland]] — hedging and stance patterns vary

legitimately; this skill must not "smooth out" deliberate hedging.

A drift away from these groundings either gets the skill updated or

gets the grounding extended; never both unchanged.