Argumentative Flow

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.
6. Hedging and stance markers are preserved. Epistemic modals ("may", "might", "could"), epistemic adverbs ("possibly", "apparently"), approximators ("approximately", "about"), attributive verbs ("we suggest", "we propose"), and indirect attributions ("it has been suggested", "it is possible that") are part of how the source calibrates the strength of its claims. Per [[esl-writers-swales-hyland]], these patterns vary legitimately across linguistic backgrounds; hedging is how scientific claims are calibrated to evidence, not stylistic noise to smooth away. A revision that drops or strengthens a hedge has weakened the author's voice and may have crossed a claim boundary. Preserve the hedge unless you can name a specific logical-coherence reason to change it; if you do change it, justify the change in the preservation report.

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. This is enforced as an active check during the inventory step (#2 of the operational protocol) and audited in the preservation report, not just a passive non-goal. The rule is preserve hedging when hedging is the mode — not refuse to revise anything that hedges. Genuine logical incoherence is still the target.

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
• 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 with which proposed changes are about logic vs. about flow. Within the preservation report, surface in one or two sentences that ESL-aware hedging preservation is happening — naming, where relevant, that a specific hedge was retained because under [[esl-writers-swales-hyland]] it is a legitimate stance choice, not imprecision. This is the skill authors most often suspect of "AI editing" rather than principled revision — the upfront explanation of the underlying theory, and the explicit ESL-aware framing in the preservation report, earn the trust the changes will need. If first invocation this session, offer /scriptorium:explain argumentative-flow so the author can learn the design before reading the revised text.

At terse and standard, the ESL-aware hedging check still runs — the inventory captures hedges and the preservation report still reports on them — but the skill does not narrate the framework. At full, the framework is surfaced briefly so the author sees why a hedge was kept. The audit fires at every level; only the framing varies.

Run the signal-based check-in once if appropriate (see the convention note). The preservation contract — every citation, statistic, declared terminology choice, and hedging marker — is never relaxed based on guidance level.

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.
   • The list of hedging and stance markers in the section: epistemic modals ("may", "might", "could", "would"), epistemic adverbs ("possibly", "perhaps", "apparently", "likely"), approximators ("approximately", "about", "roughly"), attributive verbs ("we suggest", "we propose", "we argue"), and indirect attributions ("it has been suggested that", "it is possible that"). Record each with its sentence position. This is the [[esl-writers-swales-hyland]] check: hedging force is how the author calibrates a claim against the evidence, and it varies legitimately across linguistic backgrounds. Before proposing any revision that would alter the wording of a hedged sentence, flag whether the revision drops, weakens, or strengthens the hedge — and if so, whether you can name a logical-coherence reason for the change. "Reads more naturally" is not such a reason. 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:

# 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 | ✓ |
| Hedging / stance markers | N | N | ✓ preserved (see breakdown below) |

### Hedging patterns retained vs. modified

Enumerate every hedge from the inventory in step 2 of the protocol.
Group as:

- **Retained verbatim** — list each hedge (with sentence position) that
  was kept exactly as in the source. This is the expected case.
- **Modified** — list each hedge whose surface form changed. For each,
  give: (a) source phrasing, (b) revised phrasing, (c) the
  logical-coherence reason that justified the change. Per
  [[esl-writers-swales-hyland]], "reads more naturally" is **not** a
  valid reason; legitimate reasons are limited to resolving a
  conflict with another preservation constraint or fixing genuine
  argumentative incoherence the hedge was obscuring.
- **Dropped** — list each hedge whose force was removed. Dropping a
  hedge is a higher bar than modifying one. Every entry here needs an
  explicit justification or it should be reverted.

At `full` guidance level, add one or two sentences naming that
ESL-aware preservation ran and what it caught (e.g., "retained the
hedge in sentence 3; per Swales/Hyland this is a legitimate stance
choice, not imprecision"). At `terse`/`standard`, the table and
breakdown above stand on their own — do not narrate further.

(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.
• Drop, weaken, or strengthen a hedge without a logical-coherence reason recorded in the preservation report.
• 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. Enforced as an active check during the inventory step and audited in the preservation report — not just a passive non-goal.

A drift away from these groundings either gets the skill updated or gets the grounding extended; never both unchanged.