1 Preface: Fixing Is the Other Half

Let’s be honest with each other. Finding what’s wrong with a paper is the part everybody talks about. Working out what would fix it is the part that takes the afternoon.

You’ve found the gap in Section 4. Now: is it fillable? With what hypothesis? Does adding that hypothesis break Example 3.7? Does it change what Theorem 1.1 is claiming? And once you’ve decided all that, where exactly in fifty pages of someone else’s LaTeX do the sentences go?

write-review-and-repair runs both halves.

First, write-critical-guide examines the paper and produces a graded, located ledger of issues. Then write-paper-repairs takes that ledger, works out the mathematics that closes each gap, audits every repair adversarially, and writes the ones the paper itself forces into a copy of the authors’ own source as tracked changes.

What comes back is a corrected source that compiles two ways — changes marked up for review, or silently in place — plus the repairs that were worked out but not adopted, shown in position so you can browse them, plus a report of what no repair reaches.

Nothing is applied silently, and nothing is decided for you. A repair goes in only when it is forced: when there is exactly one way to make the text consistent with what the paper already demonstrably contains. Everything else is proposed, tagged, and left for you to accept or reject one at a time.

The pipeline itself is thin. It sequences two skills that already run unattended and already share a handoff on disk, and it carries no examination or repair judgment of its own. That’s deliberate — the interesting parts belong to the stages, and the orchestrator’s whole job is to run them in order and check that the handoff between them is real.

Three chapters. Chapter 1 is the two-stage shape and why the handoff lives on disk. Chapter 2 is running it, with the repair stage covered at working depth — how it triages, what it will and won’t write into your paper, and why it applies so few. Chapter 3 is how to read what comes back and how to adopt more of it. The appendix has the markup commands and the build lines.

2 Two Stages, One Handoff

Examine, then repair. Two skills, run in order, talking to each other through a file.

2.1 The shape

Each stage runs unattended and each is useful on its own. The pipeline exists because running them back to back is what you usually want, and because the handoff between them has a failure mode worth checking every time.

2.2 The handoff is on disk

Stage one writes critical-guide/issues.yaml. Stage two reads it. That’s the entire interface.

Which means the orchestrator holds almost no state. Once stage one returns, the only thing carried into stage two is where the package landed. Everything else can be discarded, and that is what keeps the pipeline light enough to run over a long paper without the context of the examination crowding out the repairs.

It also means the stages compose in other ways. You can examine a paper today and repair it next month. You can examine it, read the guide, decide the findings are wrong, and never repair it at all. You can point stage two at a package that stage one produced in a different session on a different machine.

Between the stages, the pipeline confirms two things: that stage one’s package directory is there, and that it holds issues.yaml. If either is missing or partial it stops and reports rather than running repairs against a half-written ledger. Repairs aimed at issues that were never recorded are worse than no repairs.

2.3 Written is not accepted

The one framing that matters, and the one most likely to be lost when the pipeline is run unattended and you read the result three days later.

Stage two’s output is a marked-up build. Proposed changes are shown in position. Nothing has been applied to the paper. Running both stages back to back does not adopt anything — the person reading the result decides, tag by tag.

Even the repairs that are applied to the working copy are applied to a copy. The original source is never modified.

2.4 Reuse, don’t rebuild

If a critical-guide/ package already exists for the paper, the pipeline uses it and goes straight to repairs. Examination is the expensive half and there is no reason to pay for it twice.

Say explicitly that you want it regenerated if the paper has changed since the package was made — otherwise the old ledger is what gets repaired against, and its anchors are exactly what will fail the staleness check.

3 Running It

/write-review-and-repair ~/refereeing/descent.pdf
/write-review-and-repair arXiv:0000.00000
/write-review-and-repair ~/refereeing/descent/

It runs unattended, end to end. Both stages are invoked with their questions pre-answered, so neither stops to confirm the reader, the location, the outline, or the findings.

3.1 Stage one, in brief

The examination produces the critical-guide/ package in the paper’s own folder: the ledger, the annotated copies of the source, the typeset guide, the summary, and the audit trail of what was dropped and why.

That is a manual’s worth of material on its own, and it has one. What matters here is what stage two consumes: issues.yaml, where every finding carries a tag, a grade, an anchor into the source, a note saying what is wrong, and — ideally — a request saying what would repair it.

3.2 What stage two checks before starting

Four preconditions, in order. It refuses rather than improvising.

1. A critical-guide/ directory exists, with issues.yaml in it. There is no repair stage without an examination stage.

2. The source named in the ledger resolves.

3. Every anchor still matches that source. This is the one that matters. If anchors have stopped resolving, the source has moved on since the guide was written, and repairing against a stale ledger produces changes aimed at passages that no longer exist.

4. The issues it intends to repair carry enough to work from.

Then it copies the source — the original is never touched — and works only on the copy.

3.3 Triage, before any mathematics

The first thing stage two does with the ledger is classify it, because that determines the shape of everything after.

3.3.1 Absence or positive error

An issue saying a proof is missing, a definition is never given, a claim is asserted and never established, is an absence.

An issue saying a sign is wrong, a base ring is not commutative, a statement is false as printed, is a positive error.

Positive errors are often repairable. Absences almost never are. Supplying the missing proof of someone’s main theorem is doing the authors’ work, and — the operative point — it is not recoverable from the paper. So absences route to proposals or to the report of what cannot be repaired, and no workload gets planned around them.

Related absences get consolidated rather than enumerated. Five claims missing the same calculation is one omission affecting five passages, not five findings.

3.3.2 Groups, not items

Two repairs interact if they touch the same object, or if one’s proof cites the other’s statement. The ledger’s dependency field names some of these; it will not name all of them, and the ones it misses are the dangerous kind.

This matters because dispositions are assigned to groups. Two repairs can each be defensible alone and inconsistent together — restrict a definition to make one proof work, and every example that relied on the old generality now needs checking. Linked changes get decided together, and the disposition stays consistent across both builds.

Dependency roots are preferred, since repairing a root can retire its dependants for free, and a branch can disappear entirely once a proposed route is checked and found invalid.

3.4 Working out the repairs

For each issue it takes on: what the paper claims, what its argument establishes, what is missing between them, and the mathematics that closes the gap, written out in full.

``One would need to show that the adjunction extends” is not a repair. Where the gap cannot be closed, that is said precisely — and that is a result, not a failure. It’s what the report of unrepairable issues is made of.

It does not attempt everything. The set it takes on is one it can audit properly, weighted toward dependency roots and positive errors, and it says what it scoped and why. A silently truncated workload reads as a completed one.

3.5 The audit

Every repair goes to an independent skeptic asking four questions, not one:

1. Does it actually fix the stated problem?

2. Does it break anything else in the paper?

3. Is it minimal, or does it change more than it needs to?

4. Does it change what the paper claims?

One skeptic for a local repair; three for anything touching a hypothesis or a statement — scaled to what being wrong would cost. Each has to examine the proposed mathematics and its consequences in the paper; agreement based only on reading the ledger is not verification.

A repair that fails audit is recorded with its refutation rather than silently dropped.

3.6 Apply, propose, or escalate

The question is never how big the change is. Every repair changes what the paper says — fixing a misprinted subscript changes what a display asserts. The question is whether the repair is forced.

The test, in one sentence: could this correction be reconstructed from the paper alone, or did something have to be decided?

3.6.1 Why so few get applied

Even among forced repairs, two or three at most — unless you ask for more.

The first reason is obvious: writing into someone’s paper is a strong act and you should be the one choosing.

The second is the one that actually sets the number. Interactions scale quadratically. Three applied repairs give three pairs to check for coherence. Twenty give a hundred and ninety. The coherence check is only tractable at small numbers, and a pipeline that applied twenty repairs would be claiming a check it had not performed.

Everything else is proposed — rendered in position with its tag, so the marked-up build is a menu you browse and answer.

3.7 Two builds

The working copy compiles two ways, and which one you get is a command-line switch rather than a line anybody edits:

pdflatex -jobname paper-repaired-notes \
    paper-repaired.tex

pdflatex -jobname paper-repaired-clean \
    "\def\agenticclean{}\input{paper-repaired}"

Notes-on is the default deliberately. A file of unmarked edits that reads as the authors’ own text is the dangerous artifact, so the clean build has to be asked for.

Then both are checked: the clean build contains every applied repair and no trace of any proposal; numbered statements carry the same numbers in both builds and the same as the original; no unresolved references, and no new overfull boxes beyond the original’s.

3.8 Corrections flow back

Finding errors in the guide is an expected output, not a surprise. Writing the mathematics out is a stronger check on a finding than the finding’s own verification was, because it forces a direct comparison with the source and with every hypothesis the repair uses.

Those corrections are written to a revised ledger beside the original. The original is never overwritten — the difference between them is the audit trail.

4 Reading What Comes Back

Two packages, and a marked-up PDF that is meant to be read rather than filed.

4.1 What is on disk

<paper folder>/
  paper.tex                 the original
  paper.pdf
  critical-guide/           stage one's package
    00-guide.pdf            summary + issue list
    issues.yaml             the ledger
    issues-revised.yaml     corrections found
    annotated-*.pdf         the paper, annotated
  paper-repaired.tex        the working copy
  agentic-edits.tex         the markup, copied in
  paper-repaired-notes.pdf  marked up
  paper-repaired-clean.pdf  applied changes only
  04-proposed.md            why each proposal

Start with paper-repaired-notes.pdf. It is the document the whole pipeline exists to produce, and everything in it is tagged, so you can move between it and the issue list without translating.

4.2 The three states

Every change carries its issue tag, and every change carries a footnoted note saying why. An unexplained diff is not a repair.

Proposals show their full replacement text where the replacement would go, so you never have to open another file to learn what a proposal actually says. The reasoning behind it is in the proposals document; the text itself is in the PDF.

4.3 Answering by tag

The hand-back names the tags, and the tags are how you reply:

Apply M-5 and M-31.

That is not a text edit, and it isn’t treated as one. Each named proposal moves to applied, and then the coherence check runs again against everything already applied, and both builds are rebuilt and re-verified.

A proposal adopted in isolation is exactly the split the grouping rule exists to prevent — the repair that was defensible on its own page and inconsistent with the one three sections later.

4.4 What the markup cannot do

Three limits, worth knowing before you go looking for a bug.

A proposal cannot add a bibliography entry. A bibliography item inside a proposal block is discarded in the clean build; outside it, it leaks into a build that never proposed it. Such a source is cited as plain text in the proposal and flagged.

A tag inside mathematics is boxed, so it cannot break across lines. A tag on a long display can push the line.

Classes vary. The markup has been verified against two document classes, amsart and elsarticle, covering framed theorem environments inside and outside lists, class-defined theorem environments sharing a counter, and cancellation in displays. A third class may behave differently — and the place to find that out is a trivial change, not a deep one.

4.5 What cannot be repaired at all

The third output, and the one most likely to be skipped.

It lists the issues no repair reaches: absences that would require doing the authors’ work, and choices that sit upstream of everything else — where resolving the question one way or the other changes what a large part of the paper says.

That last category is the most useful thing in the package for a reader who has to form a judgment, because it says something no issue count can. An underdetermined repair is a different situation from a long list of fixable errors, and it is the situation the authors most need to hear about.

4.6 If a stage stops short

The pipeline reports exactly how far it got rather than papering over it.

If the handoff check failed — no critical-guide/ directory, no ledger — nothing was repaired, and the report says so and says what is needed to finish.

If stage two’s anchor check failed, the source has moved since the guide was written. Re-run the examination against the current version; the ledger is what is stale, not the paper.

And every quantity in the hand-back was measured. Counts come from the files. Durations come from timestamps recorded as the run passed each phase boundary, not from a figure quoted in an earlier report.

5 Quick Reference

5.1 Invocation

/write-review-and-repair <pdf path>
/write-review-and-repair arXiv:<id>
/write-review-and-repair <folder with the paper>

Runs unattended, end to end. Each stage can also be run alone:

# stage one only
/write-critical-guide <paper>

# stage two, against an existing package
/write-paper-repairs <paper folder>

5.2 The pipeline

5.3 Stage two’s preconditions

5.4 Dispositions

Two or three applied at most by default. Interactions scale quadratically, and the coherence check is only tractable at small numbers.

5.5 Markup states

5.6 Markup commands

\agenticaddition[M-5]{text}
\agenticremoval[M-5]{text}

% fragile tokens: \cite, \ref, \label
\agenticremovalbox[M-5]{text}

% worked out, not adopted
\agenticproposal[M-5]{replacement}

% inside an existing display
\agenticmathadd[M-5]{t}
\agenticmathdel[M-5]{t}

% a whole new list item
\agenticitem[M-5]{text}

% one line, footnoted
\agenticnote{why this change}

\begin{agenticadded}[M-5]    ...
\end{agenticadded}

\begin{agenticremoved}[M-5]  ...
\end{agenticremoved}

\begin{agenticproposed}[M-5] ...
\end{agenticproposed}

Inline commands cannot carry display math, theorem environments, or anything crossing a paragraph — use the environments for those. Always carry the tag; every change gets a note saying why.

5.7 Markup rules that came out of real use

5.8 Builds

pdflatex -jobname paper-repaired-notes \
    paper-repaired.tex

pdflatex -jobname paper-repaired-clean \
    "\def\agenticclean{}\input{paper-repaired}"

Two passes each, with bibtex between them if the paper has a bibliography. Notes-on is the default; the clean build has to be asked for.

Then verify: the clean build carries every applied repair and no proposal; statement numbers match across both builds and the original, compared through the .aux label entries rather than extracted text; no unresolved references; no new overfull boxes.

5.9 Outputs

5.10 Adopting a proposal later

Name the tags — apply M-5 and M-31. Each moves to applied, the coherence check re-runs against everything already applied, and both builds are rebuilt and re-verified. Never a text edit in isolation.

5.11 Known limits

A proposal cannot add a bibliography entry — such a source is cited as plain text and flagged. A tag inside mathematics is boxed and cannot break across lines. The markup is verified against amsart and elsarticle; another class may differ, and a trivial change is where to find that out.