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

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 and commands/ars-revision-coach.md respectively, and both leverage the academic-paper skill operating in distinct modes registered in 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). 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, 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, 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 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:

# 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:

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

This produces 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:

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:

{
  "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:

## 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, 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, 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 and 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. 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. 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}