# How the REVISE Stage (Stage 4) Works in the ARS Academic Pipeline

> Understand the REVISE stage in the ARS Academic Research Skills pipeline. Learn how structured loops and agent guidance improve manuscripts before final review.

- Repository: [Edward Cheng-I Wu/academic-research-skills](https://github.com/Imbad0202/academic-research-skills)
- Tags: how-to-guide
- Published: 2026-05-13

---

**The REVISE stage is a structured revision loop triggered by Minor or Major review decisions, where specialized agents guide authors through point-by-point responses and manuscript edits before human confirmation gates the pipeline toward re-review.**

The `Imbad0202/academic-research-skills` repository implements a rigorous academic paper development pipeline where Stage 4 (REVISE) serves as the critical bridge between initial peer review and final acceptance. This stage activates when the Review step issues **Minor** or **Major** decisions—or when an author voluntarily chooses to revise—coordinating multiple AI agents to support systematic manuscript improvement while enforcing strict loop limits to prevent infinite revision cycles.

## Trigger Conditions for Entering REVISE

The pipeline transitions into Stage 4 whenever the preceding Review decision is **not** an outright Accept. According to the architecture specification in [`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md) (lines 1004–1005), the system enters revision mode upon receiving either:

- A **Minor** revision decision requiring localized improvements
- A **Major** revision decision demanding substantial restructuring
- An explicit author choice to initiate revisions regardless of the review outcome

This trigger mechanism ensures that only manuscripts requiring genuine refinement proceed to the resource-intensive revision phase, while accepted papers bypass this stage entirely.

## Core Agent Architecture

The REVISE stage leverages the `academic-paper` skill v3.1.1 operating in *revision* mode, optionally supplemented by the *revision-coach* sub-mode for Socratic dialogue. Four specialized agents collaborate during this stage:

### The revision_coach_agent

The `revision_coach_agent` provides **Socratic guidance** through up to eight optional dialogue rounds. Rather than directly rewriting text, this agent poses targeted questions to help authors identify logical gaps and strengthen arguments independently. When the `--auto-skip` flag is used, the agent bypasses dialogue and permits other agents to apply changes directly.

### The draft_writer_agent

The `draft_writer_agent` re-enters the drafting flow to incorporate the author’s specific edits into the manuscript. This agent maintains consistency with the established writing style while integrating new content prompted by reviewer feedback.

### The argument_builder_agent

When revisions require structural changes—particularly after **Major** decisions—the `argument_builder_agent` restructures the paper’s logical framework. This agent analyzes reviewer critiques regarding argumentation flow and reorganizes sections to improve clarity and persuasiveness.

### The collaboration_depth_agent

Operating strictly as an observer, the `collaboration_depth_agent` records all interactions and revisions for the final process summary without blocking progression. This agent ensures comprehensive audit trails while remaining advisory only.

## Required Output Artifacts

Before exiting Stage 4, the pipeline must generate three concrete artifacts documented in [`academic-pipeline/SKILL.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/SKILL.md):

1. **Point-by-Point Response** – A systematic answer addressing each individual reviewer comment with specific actions taken
2. **Revised Draft** – The complete manuscript after incorporating all author-sanctioned changes
3. **Delta Report** – A concise "what changed & why" summary highlighting modifications relative to the previous version

These artifacts persist in the passport file ([`passport.yaml`](https://github.com/Imbad0202/academic-research-skills/blob/main/passport.yaml)) and serve as immutable records of the revision process.

## Human-in-the-Loop Decision Gates

### The Confirmation Checkpoint

The REVISE stage implements a **decision-heavy checkpoint** marked "🧑 Decision-heavy checkpoint" in the architecture diagram. After agents complete their processing, the system presents the revised draft to the user, who must **confirm the changes** before the pipeline can continue. This human gate prevents automated progression with unsatisfactory revisions.

### Machine Validation During Review

While authors evaluate revisions, the system tracks a **score trajectory** per rubric dimension—including clarity, novelty, and rigor. Any regression in a specific dimension is immediately **flagged** for the user’s attention, ensuring that fixes for one reviewer concern do not inadvertently degrade other quality metrics.

## State Transitions and Loop Constraints

The `pipeline_orchestrator_agent` manages strict state transitions from Stage 4 based on user confirmation:

- **If changes are accepted**: The pipeline advances to **Stage 3′ (RE-REVIEW)** for a verification pass
- **If changes are rejected**: The author may re-enter the revision loop once, proceeding to **Stage 4′ (RE-REVISE)**

The architecture enforces a **maximum of one RE-REVISE round** (Stage 4′), limiting total revision loops to **two across Stages 4 and 4′**. The `state_tracker_agent` monitors these counters to prevent infinite back-and-forth cycles, as specified in [`academic-pipeline/agents/state_tracker_agent.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/agents/state_tracker_agent.md).

## Practical Implementation Commands

Invoke the REVISE stage using the command-line interface defined in [`commands/ars-revision.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/commands/ars-revision.md):

```bash

# Start revision after a Minor or Major review decision

ars-revision --mode revision \
    --input passport.yaml \
    --output revised_passport.yaml

```

For interactive Socratic coaching (documented in [`commands/ars-revision-coach.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/commands/ars-revision-coach.md)):

```bash

# Launch revision-coach with up to 8 dialogue rounds

ars-revision-coach \
    --checkpoint-id 4 \
    --max-rounds 8

```

To inspect the Delta Report after completion:

```bash

# Extract delta report from the revised passport

cat revised_passport.yaml | jq '.artifacts.delta_report'

```

## Summary

- The **REVISE stage** activates upon **Minor** or **Major** review decisions, requiring human confirmation to exit
- Four specialized agents collaborate: `revision_coach_agent` (Socratic guidance), `draft_writer_agent` (content integration), `argument_builder_agent` (structural changes), and `collaboration_depth_agent` (observation)
- Mandatory outputs include the **Point-by-Point Response**, **Revised Draft**, and **Delta Report**
- The system enforces a **maximum of two revision loops** (Stage 4 plus one RE-REVISE in Stage 4′) to prevent indefinite cycling
- Machine checks track **score trajectories** per rubric dimension and flag any quality regressions during revisions

## Frequently Asked Questions

### What triggers entry into the REVISE stage?

Entry occurs when the Review step returns a **Minor** or **Major** decision rather than Accept, or when the author explicitly opts to revise. The `pipeline_orchestrator_agent` evaluates the review decision field in the passport file to determine eligibility for Stage 4 activation.

### What is the maximum number of revision loops allowed?

The architecture permits **two total revision loops**: the initial REVISE stage (Stage 4) and optionally one **RE-REVISE** round (Stage 4′). The `state_tracker_agent` enforces this limit by incrementing counters stored in the passport metadata, preventing infinite back-and-forth cycles between authors and reviewers.

### What artifacts must be produced before leaving the REVISE stage?

Three artifacts are mandatory: a **Point-by-Point Response** addressing each reviewer comment, the **Revised Draft** manuscript, and a **Delta Report** summarizing changes. These are formally specified in [`academic-pipeline/SKILL.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-pipeline/SKILL.md) and validated before the system permits progression to the confirmation checkpoint.

### How does the system prevent quality regression during revisions?

During the human review of revisions, the system monitors **score trajectories** across all rubric dimensions (clarity, novelty, rigor). Any decline in scores triggers immediate flags alerting the author to potential regressions, ensuring that addressing one critique does not compromise other aspects of the manuscript.