Discovery & Investigator Agents
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
In the Roughly framework, the Discovery and Investigator agents serve as the specialized "Stage 2" research components of the development pipeline. These agents are dispatched by the orchestrator (the build or fix skill) to perform deep codebase analysis before any implementation planning begins. Their primary goal is to provide the orchestrator with the necessary technical context, identifying existing patterns, root causes, and potential risks to ensure the subsequent implementation plan is accurate and feasible.
The Discovery Agent is utilized during the Build Pipeline to scope new features, while the Investigator Agent is used within the Fix Pipeline to diagnose bugs. Both agents operate under a "read-only" constraint, meaning they explore and analyze the codebase without modifying any source files.
Sources: agents/discovery.md:6-14, agents/investigator.md:6-14, README.md:143-157
The Discovery Agent
The Discovery Agent is responsible for researching and scoping features before implementation planning. It explores the codebase to understand existing architecture, utilities, and patterns relevant to a new feature.
Operational Process
The Discovery Agent follows a structured six-step process to gather intelligence:
- Read project context: Loads
CLAUDE.mdand.roughly/known-pitfalls.md. - Understand the feature: Parses the input feature description or spec.
- Find relevant code: Searches for existing patterns and components.
- Identify reuse opportunities: Locates existing functions or hooks to build upon.
- Map blast radius: Identifies files likely to be affected and integration points.
- Note risks: Checks for relevant pitfalls and potential breaking points.
Sources: agents/discovery.md:16-25
Discovery Data Flow
The following diagram illustrates how the Discovery Agent fits into the initial stages of the Build pipeline:
The Discovery Agent provides the technical foundation for the implementation plan.
Sources: agents/discovery.md:16-25, README.md:214-220
The Investigator Agent
The Investigator Agent is a specialized diagnostic tool used to identify the root causes of bugs. It is automatically offered as an upgrade once a project reaches a maturity level of 50+ source files.
Core Responsibilities
Unlike the Discovery agent which looks for patterns to build upon, the Investigator focuses on execution paths and symptoms to find where code is failing.
| Action | Description |
|---|---|
| Parse Issue | Extracts symptoms and reproduction steps from text or files. |
| Form Hypotheses | Lists likely root causes based on symptoms. |
| Trace Code Paths | Follows execution paths to validate or eliminate hypotheses. |
| Evidence Gathering | Greps for error messages and checks recent git changes. |
| Fix Scoping | Identifies the minimal set of files required for a fix. |
Sources: agents/investigator.md:16-25, README.md:267-270
Investigator Pipeline Integration
In the fix pipeline, the Investigator replaces the Discovery stage to provide a diagnostic report.
Technical Specifications
Agent Configurations
Both agents share similar toolsets and operate primarily on the Sonnet model.
| Agent | Model | Tools | Trigger |
|---|---|---|---|
| Discovery | Sonnet | Glob, Grep, Read, Bash | /roughly:build Stage 2 |
| Investigator | Sonnet | Glob, Grep, Read, Bash | /roughly:fix Stage 2 (if 50+ files) |
Sources: agents/discovery.md:1-4, agents/investigator.md:1-4, CLAUDE.md:79-84
Shared Execution Preamble
Both agents are required to load the project's canonical context before performing any analysis. This is a manual sync requirement across all agent definitions.
Before starting your task, read these files:
1. CLAUDE.md -- project conventions, commands, and stack
2. .roughly/known-pitfalls.md -- known issues to avoid repeating
Sources: agents/agent-preamble.md:18-20, agents/discovery.md:17, agents/investigator.md:17
Output Structure
The agents must produce structured reports to feed into the Planning stage (Stage 3) of their respective pipelines.
Discovery Report Components:
- Existing Patterns: Relevant files and functions found.
- Reuse Opportunities: Code implementation should leverage.
- Blast Radius: Files likely affected and integration points.
- Risks & Pitfalls: Potential issues identified.
Investigation Report Components:
- Issue Summary: One paragraph describing the bug.
- Root Cause: Hypothesis supported by file and line references.
- Alternative Causes: Possibilities if confidence is not high.
- Proposed Fix: Specific approach on what to change and why.
Sources: agents/discovery.md:27-41, agents/investigator.md:27-48
Summary
The Discovery and Investigator agents are critical specialized subagents that ensure Roughly's implementation plans are grounded in the actual state of the codebase. By separating research (Stage 2) from planning (Stage 3) and implementation (Stage 5), Roughly prevents context overflow and ensures that implementation subagents receive highly accurate, context-aware instructions. The Discovery agent enables efficient feature expansion through pattern reuse, while the Investigator agent provides the deep diagnostics necessary for robust bug resolution in mature projects.
Sources: README.md:143-157, CLAUDE.md:88-100