Route Researcher Architecture

Route Researcher Architecture

Overview

The route-researcher skill uses a hybrid architecture combining:

• Python scripts for deterministic API calls (weather, air quality, daylight, peakbagger stats)
• LLM agents for tasks requiring judgment (web scraping, content extraction, report writing, validation)

This approach minimizes token usage while maximizing parallelism and reliability.

Components

Python Scripts (tools/)

Agent Types (3 total)

Orchestrator (SKILL.md)

The orchestrator handles:

• Peak identification (Phases 1-2)
• Coordinating parallel data gathering (Phase 3)
• Data synthesis and analysis (Phase 4)
• Agent dispatch and result aggregation (Phases 3, 5, 6)
• User presentation (Phase 7)

Execution Flow

User Request
    │
    ▼
Phase 1-2: Peak Identification
    │ (peakbagger-cli search/info)
    ▼
Phase 3: Data Gathering (PARALLEL)
    ┌─────────────────────────────────────────────┐
    │  Python: fetch_conditions.py                │
    │  (weather, air quality, daylight,           │
    │   avalanche, peakbagger stats)              │
    ├─────────────────────────────────────────────┤
    │  Agent 1: PeakBagger + SummitPost           │
    │  Agent 2: WTA + Mountaineers                │
    │  Agent 3: AllTrails                         │
    │  (each fetches route info + trip reports)   │
    └─────────────────────────────────────────────┘
    │
    ▼
Phase 4: Analysis (orchestrator inline)
    │ (route type, crux, hazards, time estimates)
    ▼
Phase 5: Report Writer Agent
    │ (generates markdown from data package)
    ▼
Phase 6: Report Reviewer Agent
    │ (validates and fixes issues)
    ▼
Phase 7: Present to User

Data Contracts

All agents return JSON matching explicit schemas defined in SKILL.md.

Researcher Agent Output

{
  "sources": ["PeakBagger", "SummitPost"],
  "route_info": [
    {"source": "...", "name": "...", "difficulty": "...", "description": "...", "hazards": [...]}
  ],
  "trip_reports": [
    {"source": "...", "date": "...", "author": "...", "url": "...", "summary": "...", "conditions": "..."}
  ],
  "gaps": ["what couldn't be fetched and why"]
}

Report Writer Output

{
  "status": "SUCCESS",
  "file_path": "/path/to/report.md",
  "filename": "YYYY-MM-DD-peak-name.md",
  "sections_generated": N
}

Report Reviewer Output

{
  "status": "PASS | PASS_WITH_FIXES | FAIL",
  "issues_found": N,
  "fixes_applied": ["description of fixes"],
  "remaining_issues": [],
  "report_path": "/path/to/report.md"
}

Error Handling

Minimum viable report: Peak metadata + at least one route source + conditions data.

Design Decisions

Why Python for API calls?

• Deterministic: No LLM judgment needed for structured API responses
• Reliable: No prompt variability
• Fast: Direct HTTP calls, no agent overhead
• Cheap: Zero tokens for weather/daylight/air quality

Why inline agent prompts?

• Reliable: No "read instructions from file" failure mode
• Self-contained: Agent has everything it needs in the prompt
• Explicit contracts: JSON output format clearly specified
• Testable: Can verify prompt produces expected results

Why 3 researcher agents (not 5)?

• Balance: Enough parallelism without coordination overhead
• Source grouping: Related sources assigned together (PeakBagger+SummitPost, WTA+Mountaineers)
• Trip report batching: Each agent fetches its own reports (no separate fetch step)

Maintenance

To modify agent behavior:

1. Edit the inline prompt in SKILL.md (Phases 3, 5, or 6)
2. Update the JSON output contract if needed
3. Test with a real peak to verify changes work

To add new data sources:

1. Decide if it's API-based (add to fetch_conditions.py) or web-based (add to a Researcher agent)
2. Update the relevant component
3. Update data aggregation in Phase 3C
4. Update Report Writer prompt if new sections needed