Company Research
Workflow
- •Check prior research:
get_hypotheses(company)-- present any existing findings to user - •Estimate cost:
estimate_run(company, url, mode)-- always before starting - •Get user approval: show estimated cost and duration
- •Start research:
research_company(company, url, mode)-- returns job_id immediately - •Monitor: poll
check_jobs()every 2 minutes until complete - •Present results: show report path and any new hypotheses
Research Modes
See references/modes.md for mode details (cost, duration, use cases).
Hypothesis Management
When user confirms or rejects a claim during research:
code
save_hypothesis(company, hypothesis_id, "validated", evidence) save_hypothesis(company, hypothesis_id, "invalidated", evidence)
Error Handling
| Error | Resolution |
|---|---|
budget_exceeded | Hook blocked operation; request budget increase |
ssrf_blocked | URL failed security check; use deep mode instead |
qa_below_threshold | Report quality low; suggest refinement |
job_already_running | Wait for current job; use check_jobs |
Example Workflow
code
User: "Research Acme Corp at https://acme.com"
1. get_hypotheses("Acme Corp")
-> Found 2 prior hypotheses from last session
2. Present to user:
"I found prior research on Acme Corp:
- [VALIDATED] Uses microservices architecture
- [UNTESTED] Revenue growth exceeds 20% YoY
Shall I continue with new research?"
3. estimate_run("Acme Corp", "https://acme.com", "full")
-> Cost: $1.20, Time: ~30 minutes
4. Request approval:
"Full research will cost ~$1.20 and take ~30 minutes.
Reply 'approve' to proceed."
5. research_company("Acme Corp", "https://acme.com", "full")
-> Job started: job_abc123
6. Poll check_jobs() until complete
7. Present results and new hypotheses
Constraints
- •Single Job: Only one research job at a time
- •Cost Awareness: Always estimate before running
- •Memory Persistence: Hypotheses survive across sessions
- •QA Gate: Reports below score 70 trigger warnings