manuscript-revision

name

manuscript-revision

description

Use when the user asks to revise, polish, improve, critique, or finalize an existing academic draft — manuscripts, papers, theses, chapters, dissertations. Trigger phrases "revise this draft", "polish this chapter", "finalize this manuscript", "improve this paper", "critique this section", "review this thesis". Do NOT use for first-draft writing or blank-page work — this skill's doctrine applies once a draft exists and is ready for revision.

Manuscript revision

No pre-flight, no bootstrap by design. This skill is doctrine — why revision works the way it does. Execution lives in the critic-loop skill, which runs its own check_configured.py pre-flight. If the user invokes the critic loop in an unconfigured project, the loop will route them to setup. Don't replicate that check here.

Core rule

Academic prose is revised against multiple parallel critic perspectives, not polished in a single pass. After drafting (or after any substantial revision), run the critic loop via the critic-loop skill: tests must pass → render → parallel critic subagents → adjudicate → revise → repeat until no critic asks for a MAJOR revision. The loop has explicit termination rules; do not exit early and do not paper over unresolved MAJOR issues.

This skill is the doctrine — why revision works this way and what the critics are for. The critic-loop skill is the procedure — how to actually run it, with CLI flags, Agent prompts, and file schemas. Read critic-loop for the executable details; everything below is the justification for that procedure's shape.

Before the loop: academic-style governs prose conventions (topic sentences, active voice, hedging, term definitions) at drafting time. Applying it before the first critic-loop run reduces how many MAJOR/MINOR style issues the argument critic raises — fewer iterations to convergence. This skill and critic-loop cover when and why to revise; academic-style covers how the prose should read throughout.

Why a loop, not a pass

A single critic produces a shallow pass. Four differently-framed critics catch non-overlapping classes of problem — each perspective covers one independent axis on which an academic paper can fail:

• evidence — are the paper's factual claims honestly supported by the sources and data it invokes? Catches fabricated findings, direction reversals, misattributed citations, and prose numbers that don't match the pipeline output.
• method — is the procedure defensible and transparently disclosed? Catches causal overreach, thin limitations, missing validity threats, and under-disclosed tools / prompts / models. Reviewer #2 energy.
• argument — does the prose make a coherent case from research question to contribution? Catches scope drift, structural incoherence, one-paper-at-a-time narration in review papers, undefined terms, and framing that doesn't match the target venue.
• expert — does the manuscript hold up against what a senior reviewer in the field already knows? Catches missing seminal works, dated framings, contradictions with well-established findings, and claimed "gaps" that aren't actually gaps.

Running them in parallel keeps latency ≈ max-of-four rather than sum-of-four. Running them against a rendered build — not the authoring source — means they evaluate what the reader will see (resolved tables, inline expressions, citations), not what the author typed.

What critics do not do

• Critics don't rewrite. They flag; the main agent adjudicates and applies.
• Critics don't rerun tests. The main agent gates each iteration on tests passing; critics only ever see green builds.
• Critics don't adjudicate between each other. When they disagree, the main agent writes a brief adjudication note and decides.
• Critics don't see the authoring source. They see the rendered markdown so they evaluate what the reader sees.

See also

• critic-loop — the executable procedure: CLI arguments, the generic prompt preamble, the four default perspective prompts, termination conditions, the decisions.md / final-report.md schemas, and full red-flags list. Single source of truth for how the loop actually runs.
• fact-check — the standalone audit. Use fact-check for pre-revision citation audits, supervisor hand-offs, or pre-submission spot-checks. During revision, the evidence critic inside the critic-loop audits citations on every iteration — do not run both on the same draft in the same session (they share the verifying-citations doctrine and would burn MCP / Zotero quota twice). MAJOR / MINOR severity for citation issues is defined in verifying-citations; expert-/argument-/method-critic MAJORs are defined inline in their perspective prompts in the critic-loop skill.
• grounded-citations — governs citation hygiene during both drafting and revision. When a critic flags a weak citation, the fix goes through grounded-citations' four-part rule (Zotero-backed BBT key, externalised consultation, claim-supporting source).
• empirical-integrity — governs how numbers enter prose. When a critic suggests sharpening a statistic, the fix must route through the pipeline (inline expression reading analysis/results/) — never hand-typed. Critics must not be used to bypass this rule.