# How to Initiate a Revision Process in the ARS Pipeline: 3 Steps Explained

> Learn how to initiate a revision process in the ARS pipeline with our easy 3-step guide. Discover how to invoke slash commands and generate revised manuscripts efficiently.

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

---

**You initiate a revision process in the ARS pipeline by invoking the `/ars-revision` slash command, which triggers the `revision_coach_agent` to parse reviewer comments into a structured roadmap and then dispatches the `draft_writer_agent` to generate a revised manuscript and response letter.**

The ARS (Academic Research Skills) pipeline, maintained in the `Imbad0202/academic-research-skills` repository, provides a dedicated revision workflow that transforms peer review feedback into a polished manuscript revision. Understanding how to initiate a revision process in the ARS pipeline ensures you leverage the automated orchestration between specialized agents while maintaining strict mode isolation and contract-driven handoffs.

## Overview of the ARS Revision Workflow

The revision workflow consists of three logical stages orchestrated by the pipeline orchestrator. Unlike ad-hoc editing, this process treats reviewer comments as structured data, mapping them to specific paper sections before any rewriting occurs.

The pipeline distinguishes between two entry points:
- **`/ars-revision`** – Executes the full revision cycle (roadmap creation + manuscript rewrite)
- **`/ars-revision-coach`** – Generates only the Revision Roadmap and Response Letter Skeleton without modifying the manuscript

These commands are defined in [`commands/ars-revision.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/commands/ars-revision.md) and [`commands/ars-revision-coach.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/commands/ars-revision-coach.md) respectively, and both leverage the `academic-paper` skill operating in distinct modes registered in [`MODE_REGISTRY.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/MODE_REGISTRY.md).

## Step-by-Step Guide to Initiating the Revision Process

### Step 1: Trigger Revision Mode

To begin, invoke the revision mode through either the slash command or CLI wrapper. This signals the orchestrator to load the `revision` (or `revision-coach`) mode from the **MODE_REGISTRY** and prepare the agent dispatch sequence.

When you run `/ars-revision`, the orchestrator immediately isolates this workflow from standard drafting modes. This isolation ensures that the heavy-weight drafting agents (Sonnet) remain separate from the lighter comment-parsing agent (Opus), optimizing token cost and preventing context contamination.

### Step 2: Parse Reviewer Comments and Build the Roadmap

Once triggered, the pipeline instantiates the `revision_coach_agent` (specified in [`academic-paper/agents/revision_coach_agent.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-paper/agents/revision_coach_agent.md)). This agent performs the critical analysis phase:

- Parses raw reviewer comments from any supplied format (txt, pdf, or markdown)
- Classifies each comment by type: **Major**, **Minor**, **Editorial**, or **Positive**
- Maps comments to specific paper sections (Introduction, Methods, Results, etc.)
- Assigns priorities (P1: Must Fix, P2: Should Fix, P3: Consider)
- Emits a structured **Revision Roadmap** plus an optional **Response Letter Skeleton**

The roadmap follows strict JSON contracts defined in [`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md), ensuring that downstream agents can reproducibly consume each item.

### Step 3: Apply the Roadmap and Generate the Revised Draft

With the roadmap validated, the orchestrator re-dispatches the `draft_writer_agent` (and optionally the `argument_builder_agent`) with the roadmap items injected as prompts. This agent:

- Rewrites specific sections according to the priority-ordered roadmap
- Maintains consistency with the original paper's argumentation
- Generates a delta report documenting what changed and why

The output includes the **revised draft**, the **Revision Roadmap**, and the **Response Letter**. According to [`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md), the revision loop can repeat automatically if the evaluator raises new mandatory findings, though the architecture enforces a **revision loop cap** of 2 total iterations across stages 4 and 4' to prevent endless recursion.

## Why This Architecture Matters

The ARS revision pipeline employs three architectural safeguards that distinguish it from simple prompt chaining:

**Mode Isolation** – The **MODE_REGISTRY** treats `revision` and `revision-coach` as distinct operational modes. This separation ensures that comment parsing (lightweight) and manuscript rewriting (compute-intensive) use appropriately sized models without context bleeding.

**Contract-Driven Handoffs** – The handoff schemas in [`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md) define exact JSON contracts between the revision coach and drafting agents. Every roadmap item must conform to this schema, ensuring that priority levels, section mappings, and suggested actions are machine-readable and reproducible.

**Revision Loop Safety** – The architecture caps revision loops at 2 total iterations across stages 4 and 4'. Once this cap is reached, the pipeline forces advancement to the next stage, preventing infinite recursion in cases of persistent evaluator objections.

## Code Examples and Implementation

### Using the Built-in CLI Command

Initiate a full revision cycle from the command line:

```bash

# Start a revision (full draft rewrite)

ars-revision \
  --comments path/to/reviewer_comments.txt \
  --draft   path/to/current_manuscript.md

```

The CLI wrapper reads both files, sends the comments to the `revision_coach_agent`, and routes the resulting roadmap to the drafting agents.

### Using the Revision-Coach Command (Roadmap Only)

Generate a roadmap without rewriting the manuscript:

```bash
ars-revision-coach \
  --comments reviewer_feedback.pdf \
  --draft   manuscript.md \
  --output  revision_roadmap.md

```

This produces [`revision_roadmap.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/revision_roadmap.md) containing a structured markdown table of comments and a response-letter skeleton.

### Direct API Call (JSON Payload)

For service integration, send a POST request:

```json
POST https://api.ars.example.com/v1/execute
{
  "command": "ars-revision",
  "payload": {
      "comments": "BASE64_ENCODED_REVIEWER_TEXT",
      "draft":    "BASE64_ENCODED_MANUSCRIPT"
  }
}

```

The service responds with:

```json
{
  "revised_draft": "BASE64_ENCODED_NEW_MANUSCRIPT",
  "roadmap": "BASE64_ENCODED_ROADMAP_MD",
  "response_letter": "BASE64_ENCODED_LETTER_MD"
}

```

### Inspecting the Revision Roadmap

The `revision_coach_agent` generates structured output similar to this:

```markdown

## Revision Roadmap

### Overview

- Decision: **Major Revision**
- Total comments: 27
- By type: 8 Major / 12 Minor / 5 Editorial / 2 Positive

### P1: Must Fix

| # | Comment Summary                      | Reviewer | Type   | Section   | Suggested Action |

|---|--------------------------------------|----------|--------|-----------|------------------|
| 1 | Add a power analysis for the sample  | R2       | Major  | Methods   | Run post-hoc power calculation |
| 2 | Clarify the definition of "X"        | R1       | Major  | Introduction | Add a formal definition |

```

## Summary

- **Initiate the process** by calling `/ars-revision` (full rewrite) or `/ars-revision-coach` (roadmap only) to trigger the pipeline orchestrator.
- **Analyze feedback** through the `revision_coach_agent` at [`academic-paper/agents/revision_coach_agent.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-paper/agents/revision_coach_agent.md), which classifies comments and builds a priority-ordered Revision Roadmap.
- **Generate output** via the `draft_writer_agent` at [`academic-paper/agents/draft_writer_agent.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/academic-paper/agents/draft_writer_agent.md), producing a revised manuscript, delta report, and response letter.
- **Respect safeguards** including the revision loop cap (2 iterations) and contract-driven handoffs defined in [`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md) and [`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md).

## Frequently Asked Questions

### What is the difference between `/ars-revision` and `/ars-revision-coach`?

**`/ars-revision`** executes the complete pipeline: parsing comments, building the roadmap, and rewriting the manuscript. **`/ars-revision-coach`** stops after the analysis phase, outputting only the Revision Roadmap and Response Letter Skeleton without touching the original draft. Use the coach mode when you want human review of the roadmap before committing to rewrites.

### How does the ARS pipeline prevent infinite revision loops?

The architecture enforces a **revision loop cap** of 2 total iterations across stages 4 and 4', as documented in [`docs/ARCHITECTURE.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/docs/ARCHITECTURE.md). If the evaluator raises new mandatory findings after the second iteration, the pipeline forces advancement to the next stage rather than initiating a third revision cycle.

### What file contains the JSON contract definitions for agent handoffs?

The handoff schemas are defined in [`shared/handoff_schemas.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/handoff_schemas.md). This file specifies the exact JSON structure that the `revision_coach_agent` must produce and that the `draft_writer_agent` must consume, ensuring that roadmap items include fields for priority, section mapping, reviewer attribution, and suggested actions.

### Can I use the revision process without generating a full manuscript rewrite?

Yes. Use the **`/ars-revision-coach`** command defined in [`commands/ars-revision-coach.md`](https://github.com/Imbad0202/academic-research-skills/blob/main/commands/ars-revision-coach.md). This mode invokes only the `revision_coach_agent` to parse your reviewer comments and generate a structured roadmap and response letter skeleton, leaving your original manuscript unchanged while providing a clear action plan for manual editing.