What Types of Edits Does the Reviewer Agent Suggest in the AI Job Search Workflow?

The reviewer agent suggests two distinct categories of feedback: Part A provides machine-readable JSON edit instructions for automatic application, while Part B delivers high-level narrative suggestions requiring human judgment to implement.

The MadsLorentzen/ai-job-search repository implements a sophisticated multi-agent workflow where a reviewer agent refines application materials during the /apply command execution. Understanding the specific types of edits the reviewer agent suggests is essential for customizing the drafter-reviewer pipeline and ensuring token-efficient document refinement. These edit types are defined in .claude/commands/apply.md and work in concert with verification rules specified in the writing-style skill files.

Part A – Structured JSON Edits

Structured edits represent the machine-readable portion of the reviewer’s output, designed for programmatic application without re-reading source files.

JSON Schema and File Format

According to the source code in .claude/commands/apply.md (lines 167–198), Part A returns a JSON array where each object contains three required fields:

• file: The target document path (e.g., cover_letter.txt or cv.txt)
• old_string: The exact text segment to locate and replace
• new_string: The replacement text to insert

This format enables the drafter to feed outputs directly into automated editing tools, eliminating manual search-and-replace operations and reducing token consumption in subsequent workflow steps.

[
  {
    "file": "cover_letter.txt",
    "old_string": "I am excited about the role.",
    "new_string": "I am thrilled to contribute to Acme Corp’s innovative AI team."
  },
  {
    "file": "cv.txt",
    "old_string": "Managed projects.",
    "new_string": "Led a cross-functional team to deliver a $2M SaaS product on time."
  }
]

Part B – Narrative Suggestions

Narrative suggestions comprise the human-oriented recommendations defined in .claude/commands/apply.md (lines 201–293) that require interpretive judgment to implement. These appear as free-text bullet points or prose within the reviewer’s response.

Company-Specific Angles

The reviewer identifies opportunities to weave verified research about the employer into opening paragraphs or motivation sections. These edits transform generic applications into targeted narratives that demonstrate specific knowledge of the company’s current initiatives, departmental structure, or recent achievements.

Action-Oriented Reframing

This category involves converting passive or generic phrasing into active, results-focused statements. For example, transforming "responsible for" into "oversaw" or "contributed to" into "architected and shipped." The reviewer flags verbs that obscure impact and suggests alternatives that quantify achievements.

Missing-Gap Handling

Rather than keyword stuffing to hide employment interruptions, the reviewer recommends explicitly acknowledging genuine gaps with brief, contextual explanations. This approach maintains credibility while framing gaps as periods of skill development or strategic career transitions.

General Stylistic Polish

The reviewer provides flow and tone corrections to ensure consistency with the candidate’s established voice. This includes sentence rhythm adjustments, transition improvements, and elimination of repetitive phrases that may have emerged during initial drafting.

Verification Requirements

All company-specific claims suggested in Part B must undergo independent validation before implementation. According to .claude/skills/job-application-assistant/03-writing-style.md (lines 13–19), the reviewer must verify facts using WebFetch or WebSearch tools before incorporating corporate details into the application materials. This prevents hallucinated information about potential employers from contaminating the final documents.

Applying the Review Cycle

The drafter agent processes Part A edits programmatically while reserving Part B suggestions for manual interpretation. Below is the implementation pattern used within the repository’s workflow:

# Process Part A: Structured JSON edits

review_edits = [
    {
        "file": "cover_letter.txt",
        "old_string": "I am excited about the role.",
        "new_string": "I am thrilled to contribute to Acme Corp’s innovative AI team."
    },
    {
        "file": "cv.txt", 
        "old_string": "Managed projects.",
        "new_string": "Led a cross-functional team to deliver a $2M SaaS product on time."
    }
]

# Automated application (token-efficient dispatch)

for edit in review_edits:
    apply_edit(edit["file"], edit["old_string"], edit["new_string"])

# Part B: Manual incorporation of narrative suggestions

# • Add verified paragraph about Acme Corp’s European expansion (WebSearch confirmed)

# • Replace "responsible for" with "oversaw" in experience section

# • Address one-year career gap with brief upskilling explanation

Summary

• Part A structured edits provide machine-readable JSON arrays with file paths, old strings, and new strings for automated application, reducing token usage in the /apply workflow.
• Part B narrative suggestions deliver high-level strategic advice including company angles, active voice conversion, gap acknowledgment, and stylistic consistency that requires human judgment to implement.
• Verification gates mandate WebFetch or WebSearch confirmation for all employer-specific data before inclusion in final documents.
• Source definitions reside in .claude/commands/apply.md for edit formats and .claude/skills/job-application-assistant/03-writing-style.md for validation rules.

Frequently Asked Questions

What is the exact JSON format for Part A structured edits?

Part A returns a JSON array containing objects with three fields: file (target document), old_string (text to locate), and new_string (replacement text). This format is defined in .claude/commands/apply.md lines 167–198 and enables direct ingestion by automated editing tools without file re-reading.

How does the reviewer agent handle employment gaps?

The reviewer suggests explicit acknowledgment of genuine gaps rather than obfuscation through keyword stuffing. Recommendations include brief contextual explanations that frame gaps as periods of strategic skill development or career transition, maintaining credibility while addressing potential employer concerns.

Why must company-specific details be verified before inclusion?

According to .claude/skills/job-application-assistant/03-writing-style.md lines 13–19, the reviewer enforces verification to prevent hallucinated corporate information from contaminating application materials. Claims about company initiatives, departmental structures, or recent news must be confirmed via WebFetch or WebSearch before insertion into cover letters or CVs.

Can the drafter automatically apply Part B narrative suggestions?

No. Part B suggestions require human interpretive judgment to implement. Unlike Part A’s machine-readable JSON, narrative recommendations regarding tone, company angles, and stylistic flow appear as free-text bullet points that the candidate or drafter must manually evaluate and incorporate based on context and authenticity.

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