# How the Reviewer Agent Researches Companies in AI-Job-Search

> Discover how the reviewer agent researches companies using a cache-first workflow and Gemini for web scraping in the ai-job-search repository. Learn about efficient data retrieval.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-08-28

---

**The reviewer agent follows a deterministic cache-first workflow that checks local `company_research/` files before delegating to the Gemini Research Expert for fresh web scraping, then persists new results to disk for future reuse.**

The `MadsLorentzen/ai-job-search` repository implements an intelligent agent system designed to automate job application workflows. Understanding how the reviewer agent researches companies reveals a sophisticated **cache-first architecture** that minimizes redundant API calls while ensuring access to current company intelligence.

## The Three-Phase Company Research Workflow

The reviewer agent implements a deterministic three-phase process for gathering company information, designed to optimize for both speed and accuracy.

### Phase 1: Cache-First Lookup

The reviewer agent begins every research task by inspecting the local **company research cache**. According to [`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py), the agent first checks for existing markdown files in the `company_research/` directory matching the company slug. The reviewer prompt template explicitly instructs: "*Check `company_research/<company-name>` for existing research before starting a fresh lookup*". This cache-first approach ensures repeated queries for the same company return instantly without triggering expensive web searches.

### Phase 2: Delegating to the Gemini Research Expert

When the cache lookup returns no results, the reviewer agent delegates the actual information gathering to the **Gemini Research Expert**. This specialized agent is defined in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md) and executes web research using methodologies specified in [`.claude/skills/job-application-assistant/09-web-research.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/09-web-research.md). The reviewer prompt contains the explicit instruction: "*If no cached data is found, invoke the Gemini research expert to perform a web-search*". The Gemini expert synthesizes concise company overviews from publicly available sources including company websites, news articles, and professional networks.

### Phase 3: Persisting Results to Disk

After receiving fresh research from the Gemini expert, the reviewer agent writes the results to `company_research/{company_slug}.md`. This **cache write-back** behavior ensures subsequent research requests for the same company hit the local file rather than triggering another web search. The test suite verifies this persistence logic in [`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py), specifically validating that the agent "*writes back after fresh research*" to maintain the cache integrity.

## Core Implementation Files

The company research functionality spans several key files within the repository:

- **[`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py)**: Contains the test suite that validates the cache-first behavior, including assertions around lines 101-108 for cache hits and lines 111-116 for write-back verification.
- **[`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md)**: Defines the Gemini Research Expert agent specifications that the reviewer invokes for fresh web research when cache misses occur.
- **[`.claude/skills/job-application-assistant/09-web-research.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/09-web-research.md)**: Documents the detailed web research methodology, search query construction, and source evaluation criteria used by the Gemini expert.
- **[`README.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/README.md)**: Provides the high-level architectural overview of the AI-job-search framework and its thin-pointer design philosophy.

## Implementation Example

The following Python pseudocode illustrates the logic flow implemented in the reviewer agent:

```python
import os
from pathlib import Path
from agents.gemini_research_expert import GeminiResearchExpert

class ReviewerAgent:
    CACHE_DIR = Path("company_research")

    def research_company(self, company_name: str) -> str:
        slug = company_name.lower().replace(" ", "_")
        cache_file = self.CACHE_DIR / f"{slug}.md"

        # Phase 1: Cache-first lookup

        if cache_file.is_file():
            return cache_file.read_text(encoding="utf-8")

        # Phase 2: Delegate to Gemini Research Expert

        fresh_md = GeminiResearchExpert().run_web_research(company_name)

        # Phase 3: Cache write-back

        self.CACHE_DIR.mkdir(parents=True, exist_ok=True)
        cache_file.write_text(fresh_md, encoding="utf-8")

        return fresh_md

```

To invoke this workflow within the job application pipeline:

```python
def apply_step_3(job):
    reviewer = ReviewerAgent()
    research = reviewer.research_company(job.company_name)
    # research contains markdown-formatted company intelligence

    return research

```

## Summary

- The reviewer agent implements a **cache-first architecture** that prioritizes existing `company_research/` files over fresh API calls.
- **Cache misses trigger delegation** to the Gemini Research Expert, which performs LLM-driven web searches using specifications in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md).
- **Automatic persistence** ensures research results are written back to disk, creating a reusable knowledge base that improves performance for subsequent queries.
- The entire workflow is **deterministically tested** in [`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py), validating both retrieval and storage behaviors.

## Frequently Asked Questions

### Where is the reviewer agent's company research logic defined?

The core behavior is defined through a combination of the reviewer prompt template and the test specifications in [`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py). The prompt template explicitly instructs the agent to check `company_research/<company-name>` files before invoking external research tools, while the test suite enforces this contract through assertions at lines 101-108.

### What happens when no cached research exists?

When the reviewer agent detects a cache miss (no file exists in `company_research/` for the target company), it automatically delegates to the **Gemini Research Expert**. This agent, specified in [`.claude/agents/gemini-research-expert.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/agents/gemini-research-expert.md), performs fresh web searches using the methodologies described in [`.claude/skills/job-application-assistant/09-web-research.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/09-web-research.md) to generate a comprehensive company overview.

### How does the Gemini Research Expert gather company information?

The Gemini Research Expert utilizes the web research skill defined in [`.claude/skills/job-application-assistant/09-web-research.md`](https://github.com/MadsLorentzen/ai-job-search/blob/main/.claude/skills/job-application-assistant/09-web-research.md), which outlines specific search strategies, source reliability criteria, and information synthesis techniques. The expert uses the Gemini LLM to process search results and generate concise, markdown-formatted company intelligence covering mission, products, culture, and recent news.

### Can the cache directory location be customized?

While the standard implementation uses `company_research/` as the default cache directory, the `ReviewerAgent` class defines `CACHE_DIR = Path("company_research")` as a class attribute. Modifying this path in the agent initialization allows customization of the storage location, though the test suite in [`tests/test_company_research_cache.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py) assumes the default path for validation purposes.