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

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, 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 and executes web research using methodologies specified in .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, 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: 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: 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: Documents the detailed web research methodology, search query construction, and source evaluation criteria used by the Gemini expert.
• 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:

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:

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.
• 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, 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. 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, performs fresh web searches using the methodologies described in .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, 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 assumes the default path for validation purposes.

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