# Structure of the Reviewer Agent's Prompt in the AI Job Search Repository

> Explore the modular five-section architecture of the reviewer agent's prompt in the ai-job-search repository. Understand its YAML front-matter, tool specs, methodology, guidelines, and protocols.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: internals
- Published: 2026-08-26

---

**The reviewer agent's prompt follows a modular five-section architecture defined in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md), consisting of YAML front-matter, tool specifications, research methodology, operational guidelines, and communication protocols that dynamically inject CV and cover letter drafts for inline analysis.**

The reviewer agent operates as the primary quality assurance mechanism within the `/apply` workflow of the MadsLorentzen/ai-job-search repository. Its prompt structure is designed to enforce rigorous research standards while maintaining token efficiency by passing draft content inline rather than through external file references.

## Prompt File Location and Architecture

The complete prompt definition resides in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md) within the repository's Claude framework configuration. When the `/apply` command executes, the framework spawns the reviewer by injecting this prompt inline along with the current LaTeX drafts of the CV and cover letter. This design eliminates redundant file I/O operations and ensures the agent receives a complete, self-contained context for immediate analysis.

The prompt employs plain-text Markdown-compatible formatting that the framework parses and submits to the underlying model (configured as `sonnet` in the front-matter).

## Five Core Sections of the Reviewer Agent Prompt

### Front-Matter Configuration

The prompt opens with a YAML front-matter block that declares the agent's identity and runtime parameters:

```yaml
---
name: gemini-research-expert
description: Use this agent when the user needs to perform research tasks, gather information from external sources, or investigate topics that require web searches and synthesis of information.
model: sonnet
---

```

This header identifies the agent's purpose as a research specialist capable of external information gathering and synthesis, distinguishing it from other specialized agents in the workflow.

### Your Primary Tool

The prompt specifies the exact command syntax the agent must use to execute research tasks:

```text
gemini -p "your research prompt here"

```

This directive ensures consistent tool invocation across all research operations, requiring the agent to formulate focused queries and pass them through the Gemini CLI interface.

### Your Research Methodology

This section establishes a four-phase workflow that governs every research request:

1. **Prompt Formulation** – Instructions for crafting focused Gemini prompts with specificity, context requirements, desired output formats, citation standards, and scope limitations.

2. **Research Execution** – Exact command syntax requirements including mandatory components: clear questions, evaluation criteria, and constraint definitions.

3. **Information Synthesis** – Protocols for verifying relevance, organizing findings hierarchically, documenting information gaps, and flagging methodological caveats.

4. **Quality Assurance** – Cross-referencing procedures to verify facts against multiple sources, distinguishing between established facts and emerging trends, noting data recency, and identifying potential bias in sources.

### Operational Guidelines

The prompt imposes specific behavioral constraints during research execution:

- **Explain the research strategy** before executing any commands
- **Use multiple targeted searches** when single queries prove insufficient
- **Refine prompts iteratively** based on interim results
- **Provide transparent context** with all findings, explicitly stating limitations and confidence levels

These guidelines ensure the agent maintains methodological rigor while remaining adaptable to varying research complexities.

### Communication Style

Final output standards require the agent to:

- Anticipate follow-up questions proactively
- Structure findings with clear hierarchical organization
- Evaluate source reliability critically
- Maintain efficiency by eliminating redundant information

## Dynamic Content Injection

The framework modifies the base prompt at runtime by appending the candidate's current drafts. The implementation follows this pattern:

```python
review_prompt = f"""
--- 
name: gemini-research-expert
description: Researcher for company background and draft critique
model: sonnet
---

You are an elite Research Expert ...

# Drafts

CV_DRAFT:
{cv_tex_string}

COVER_LETTER_DRAFT:
{cover_letter_tex_string}
"""

agent = AgentTool(prompt=review_prompt)
feedback = agent.run()

```

This inline injection strategy ensures the reviewer analyzes the most current iteration of application materials without requiring separate file read operations, significantly reducing token consumption and latency.

## Feedback Format and Integration

Upon completing analysis, the reviewer returns structured JSON feedback that the `/apply` command processes:

```json
{
  "edits": [
    {
      "file": "cv/main_example.tex",
      "old_string": "Old bullet point text",
      "new_string": "Rewritten bullet point with stronger metrics"
    }
  ],
  "suggestions": [
    "Add a sentence about the company's recent expansion into renewable energy.",
    "Re-phrase the motivation paragraph to align with the firm's sustainability values."
  ]
}

```

The `edits` array contains precise string replacements for automated application, while the `suggestions` array provides strategic recommendations for manual review. This bifurcation allows the framework to apply technical corrections automatically while flagging substantive content improvements for human approval.

## Related Configuration Files

Several ancillary files constrain and extend the reviewer agent's functionality:

- **[`.claude/skills/job-application-assistant/03-writing-style.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/03-writing-style.md)** – Prohibits unverified company claims and establishes tone requirements that the reviewer must enforce
- **[`.claude/skills/job-application-assistant/04-job-evaluation.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/04-job-evaluation.md)** – Defines the broader evaluation workflow where the reviewer's research feeds into final application scoring
- **[`.claude/commands/apply.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/apply.md)** – Orchestrates the reviewer spawning process and handles the JSON feedback integration

## Summary

- The reviewer agent prompt is defined in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md) using a five-section modular architecture
- **Front-matter** declares the agent identity as `gemini-research-expert` using the `sonnet` model
- **Primary Tool** specifies the `gemini -p` command syntax for all research operations
- **Research Methodology** enforces a four-phase workflow: formulation, execution, synthesis, and quality assurance
- **Dynamic injection** passes CV and cover letter drafts inline to minimize token usage and eliminate file I/O
- **JSON output** provides structured `edits` for automated application and `suggestions` for manual review

## Frequently Asked Questions

### Where is the reviewer agent prompt defined in the AI Job Search repository?

The complete prompt structure is defined in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md). This file contains the YAML front-matter, tool specifications, methodology guidelines, and communication protocols that govern the agent's behavior during the `/apply` workflow.

### How does the reviewer agent receive the CV and cover letter content?

The framework passes draft content inline at runtime by appending `CV_DRAFT` and `COVER_LETTER_DRAFT` variables to the base prompt. This injection occurs in [`.claude/commands/apply.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/commands/apply.md), ensuring the agent analyzes current document states without performing additional file reads.

### What research command does the reviewer agent use?

The prompt instructs the agent to execute all research using the syntax `gemini -p "your research prompt here"`. This standardized command ensures consistent external information gathering across all review operations.

### What format does the reviewer agent return for feedback?

The agent returns structured JSON containing two primary keys: `edits` (an array of objects specifying file paths, old strings, and replacement strings for automated corrections) and `suggestions` (an array of strings describing strategic improvements requiring manual implementation).