argumentative-flow git:20260517.8b0de03A

Immutable. This exact content never changes and is served at /api/v1/blob/2223a8d5911eec1f.

---
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/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;
  do not "smooth out" hedging that's deliberate.

## 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.