seandavi/scriptorium/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. 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; a whole-manuscript pass is outside the default scope (the single-section-unit guard below).

Guards and overrides

This skill's guards are declared in manifest.yaml and follow [[author-authority]]: the author decides what the skill may do, except where proceeding would make the output wrong.

• `single-section-unit` (scope; default refuse). If the author

asks for a whole-manuscript pass, state the concern and its source in one line: "This skill transforms one section per run so every change stays reviewable; a whole-manuscript pass is outside its default scope (single-section-unit; source: this skill's reviewability design)." Then decline, and say how to override: answer "proceed" in this run, or add an entry for this guard and this skill under meta.overrides in MANUSCRIPT_STATE.yaml. On override, work through the sections one at a time, in manuscript order, with the full output (diff and preservation report) for each section.

• Accuracy guards (fixed). preserve-cited-support,

preserve-quantities-verbatim and preserve-claim-set are the hard preservation constraints below. no-parametric-citations means no citation is ever added. no-false-verification-claims means the preservation report is never clean on unclean output. Neither a per-run answer nor meta.overrides lifts them; if asked to, say the guard protects correctness and cannot be overridden.

Read meta.overrides with the rest of MANUSCRIPT_STATE.yaml. For single-section-unit, the first of these decides: the author's answer in this run, in either direction; an entry under meta.overrides naming the guard and this skill (or "*"); the default, refuse. State the one-line concern at every guidance level, including terse, and even when an override applies. When the run proceeds past the guard, the output carries the line Overrides applied: single-section-unit (see Output format); otherwise the line is omitted.

Hard preservation constraints

These are non-negotiable. Constraints 1, 2, 5 and 6 are the skill's fixed accuracy guards (preserve-cited-support, preserve-quantities-verbatim, preserve-claim-set), and no override lifts them; terminology and voice/tone follow the state file, which the author controls. 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.

1. 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%."

1. **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.

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

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

1. 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. Do not treat sparser stance marking as the scientific norm: Hyland & Jiang (2018) found interactional metadiscourse declined in soft fields but rose in the sciences ([[esl-writers-swales-hyland]]).

If preservation conflicts with a flow improvement, preservation wins every time. Document the conflict; do not silently violate.

BERTScore and similar embedding metrics are documented to be insensitive to negation and to numerical changes ([[semantic-preservation]]), so 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). Gopen & Swan say these principles are not rules and that "any reader expectation can be violated to good effect"; report each position-based finding as a diagnosis the author can overrule, not as an error.

• 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 technical content of a methods section (protocols,

parameters, analysis choices). Improving a methods section's structure and flow is in scope, as for any other section; changing what it reports is the author's job.

• "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

<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. Do not claim that experiments show these specific principles speed reading: they have not been tested in reading-time experiments, and the supporting evidence is the general given-new literature ([[reader-expectation-approach]]). 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: