Workspace · Revision toolkit

Development docs · 996102e0

View source

Peer-review revision toolkit

Use this workspace when a manuscript has entered peer review and the revision now mixes prose changes, new analyses, changed endpoints, corrections, and final archive work. It routes each task to the smallest relevant guide or worked example while keeping the submitted record recoverable.

Revision extends the evidence history; it does not rewrite it. Keep what existed at submission distinct from work introduced after outcomes had already been inspected. A submitted 8 / 8 audit followed by a reviewer-requested 4 / 4 sensitivity amendment remains 8 / 8 submitted + 4 / 4 post-review, not “12 pre-specified analyses.”

Need the shortest route? Start with the peer-review revision checklist to classify the request and preserve timing before changing files. Then run the revision-package quickstart to create, populate, validate, and hand off the governed revision scaffold with the real CLI.

Choose what you need to do now

Classify the reviewer request

Decide whether the item is a clarification, correction, sensitivity amendment, analytical amendment, endpoint amendment, or measurement amendment before changing the record.

Open the compact checklist →

Run and preserve new analysis

Declare the post-review specification space, record whether outcomes were already seen, keep valid failures in the denominator, and save the amendment separately.

Worked reanalysis →

Write the response letter

Bind each reviewer item to its category, timing, action, evidence, manuscript location, archive location, and execution denominator.

Response-letter guide →

Record what changed

Give every material v1 → v2 change a stable ID and distinguish editorial edits from corrections and analytical amendments.

Version-change manifest →

Build the revision package

Use the real CLI to scaffold response, change, amendment, software-identity, and editor-facing evidence-map records, then validate the structural manifest.

Run the quickstart →

Run the final handoff check

Verify reviewer-item closure, temporal denominators, response/manuscript agreement, software identity, archive evidence, and unresolved limitations before resubmission.

Resubmission readiness →

Request → record → evidence map

Reviewer situation	Preserve	Do not do	Continue with
Wording is unclear; no analysis changes	response item + manuscript location	invent an analytical amendment	Response-letter guide
Reviewer asks for another threshold or exclusion	dated amendment + separate denominator	merge it into the submitted denominator	Reanalysis example
Reviewer asks for a different endpoint	endpoint-specific amendment record	mix endpoints inside one robustness denominator	Amendment guide
One valid post-review branch fails technically	valid denominator + failure reason + incomplete status	relabel `3 / 4` as `3 / 3`	Revision-package example
Review exposes a coding/import/analysis defect	superseded evidence + defect record + regenerated outputs	delete the superseded record	Version-change manifest
All reviewer work is complete	response matrix + change manifest + evidence map	rely on the response letter alone	Resubmission readiness

The minimum revision record

A reconstructable review round should answer seven questions without oral explanation:

What existed at submission?
Which reviewer item introduced this change?
Had the relevant outcomes already been inspected?
What analysis or documentation action was taken?
What is the submitted denominator and what is the post-review denominator?
Where did the manuscript change?
Which archived file supports the response?

If one of those answers is hidden in email, lab memory, or an untracked local folder, the revision record is not yet independently reconstructable.

Fast executable path

Create the governed scaffold:

gazeaudit-revision-package init \
  --output-dir revision-package \
  --project-slug my-study \
  --review-round 1

Populate the response matrix, version-change manifest, amendment folders, and editor-facing evidence map, then run:

gazeaudit-revision-package validate --root revision-package

A passing validation establishes structural provenance only. It checks the expected package files and deterministic manifest integrity; it does not certify the scientific validity of the analysis or the editorial quality of the manuscript.

Use the revision-package quickstart for the shortest end-to-end exercise. For the full break-and-repair exercise, use the revision reproducibility package worked example.

Three records that should not be collapsed

Submitted

The endpoint, decisions, valid denominator, successes, failures, software identity, and claims that existed before peer-review amendments.

Post-review

Reviewer-triggered clarifications, sensitivity analyses, analytical changes, endpoint additions, measurement changes, and corrections, each with timing.

Final handoff

The revised manuscript, response matrix, version-change manifest, evidence map, software record, limitations, and publication-associated archive.

The final archive can contain all three layers, but they should remain identifiable as different temporal records.

Worked routes

One sensitivity amendment

Use the reviewer-requested reanalysis example when the main challenge is adding one post-review analysis without rewriting the submitted declaration.

Multiple reviewer items

Use the revision response package example when clarification, new analysis, and endpoint changes must all agree across the response letter, manuscript, and archive.

Fast package creation

Use the revision-package quickstart when you want the shortest real-CLI path from a synthetic reviewer request set to a structurally validated evidence package.

Executable package validation

Use the reproducibility-package CLI example when you want to create the actual scaffold, deliberately break a governed file, see the validator fail, and repair it.

Complete submission → final record

Use submission-to-accepted-record to trace the synthetic submitted 8 / 8 record, reviewer-requested 4 / 4 amendment, separate endpoint amendment, response matrix, version manifest, final evidence map, and publication-associated archive.

Five-minute pre-resubmission check

Before the revised manuscript leaves the team, verify that:

every reviewer item has a stable disposition;
every new analysis is labelled with its post-review timing;
submitted and post-review denominators are not collapsed;
failed valid branches remain visible;
endpoint amendments remain endpoint-specific;
corrections retain superseded evidence and affected-claim provenance;
response wording matches manuscript wording;
every material response points to real archived evidence;
the final software identity is recorded;
the evidence map points from each final claim component back to its temporal evidence layer.

Then run the fuller resubmission readiness and editor handoff gate.

Evidence boundaries

This toolkit is provenance infrastructure, not an acceptance predictor. It does not decide whether a reviewer request is scientifically justified, whether a model is appropriate, whether an effect is robust, whether a manuscript should be accepted, or whether editorial acceptance validates a result. Those remain separate scientific and editorial judgements.

GazeAudit’s frozen empirical case-study outcomes are unchanged and remain authoritative only within their own protocols: GazeBase incomplete, Korthals robust_negative, and Pedrotti/de Chambrier materially_fragile. The reviewer examples linked from this page are synthetic teaching material.

Full review route

For the complete interpret → draft → reconstruct → amend → respond → archive sequence, continue to the manuscript review path. For durable publication provenance after the revision is finalized, continue to the reproducible publication workflow.