Research Agent

The Research Agent (RESEARCH) is your specialist in technical research, knowledge management, and building comprehensive research prompts. This agent gathers information from authoritative sources, synthesizes findings, and maintains a searchable index of research for future reference.

Capabilities

• Web Research: Search official documentation and authoritative sources for technical information
• ChatGPT Prompt Building: Create comprehensive research prompts requesting implementation plans, code snippets, ADR drafts, story breakdowns, and more
• Research Note Curation: Save structured research findings to docs/10-research/ with consistent formatting
• Research Index Maintenance: Keep docs/10-research/README.md updated with newest research first
• Stale Research Detection: Identify research >90 days old that may need refresh
• Research Gap Identification: Flag missing research for technical decisions and ADRs
• Agent Coordination: Notify requesting agents when research is complete via bus messages

When to Use

Use this agent when you need to:

• Research a technical topic or technology choice
• Understand trade-offs between different approaches
• Build a comprehensive ChatGPT prompt for deeper analysis
• Document findings in structured format for future reference
• Update outdated research findings (>90 days old)
• Find what research already exists before making decisions
• Support ADR creation with technical background research
• Get implementation guidance for a feature approach

How It Works

Web Research Workflow

1. Understanding: Agent clarifies the research question and constraints
2. Search: Agent searches official documentation and authoritative sources (WebSearch, WebFetch)
3. Gathering: Agent collects key findings - approaches, trade-offs, best practices, benchmarks
4. Synthesis: Agent organizes findings into structured format
5. Saving: Agent saves research to docs/10-research/<YYYYMMDD>-<slug>.md
6. Indexing: Agent updates docs/10-research/README.md with entry in chronological table
7. Coordination: Agent posts bus message to notify requesting agent

ChatGPT Research Prompt Workflow

1. Context Loading: Agent reads CLAUDE.md, context.md, status.json, related ADRs, existing research to avoid duplication

2. Understanding: Agent clarifies research topic and specific questions needing answers

3. Prompt Building: Agent creates comprehensive prompt requesting:

   • TL;DR summary
   • Step-by-step implementation plan with file paths
   • Minimal runnable code snippets (copy-paste ready)
   • Configuration and environment setup
   • Error handling patterns
   • Observability and analytics hooks
   • Test examples (unit, integration, E2E)
   • Manual testing checklist
   • Security and privacy considerations
   • ADR draft with options and pros/cons
   • Story breakdown with Given/When/Then acceptance criteria
   • Rollback plan and risks
   • PR body template
   • Official documentation sources only (cited with title, URL, date)

4. Output: Agent provides prompt as code block for easy copy-paste

5. Processing: User pastes ChatGPT results back to Claude

6. Saving: Agent saves results to docs/10-research/<YYYYMMDD>-<slug>.md

7. Indexing: Agent updates research index

8. Notification: Agent notifies requesting agent via bus message

Example

Copy# Via /babysit
/agileflow:babysit
> "Need to research JWT vs OAuth2 for authentication"

The Research Agent would:

1. Search authoritative sources (JWT RFC, OAuth2 spec, security.com articles)
2. Gather key findings (stateless vs stateful, refresh tokens, delegation, use cases)
3. Create a research note comparing approaches
4. Save to docs/10-research/20251021-jwt-vs-oauth2.md
5. Update research index
6. Post bus message: "Research complete: JWT vs OAuth2 saved to docs/10-research/20251021-jwt-vs-oauth2.md"

Key Behaviors

• Official Sources Only: Research cites official documentation, not random blog posts
• Comprehensive Prompts: ChatGPT prompts are thorough, requesting implementation details, tests, security considerations, and ADR drafts
• Structured Formatting: All research follows consistent structure (summary, findings, recommended approach, trade-offs, sources)
• Stale Detection: Identifies research >90 days old and flags for potential refresh when tech has changed
• No Duplication: Checks existing research before starting new research
• Agent Coordination: Notifies requesting agents immediately when research complete
• Clear Sourcing: All research cites sources with title, URL, and retrieval date

Tools Available

This agent has access to:

• Read: Browse research files and understand existing findings
• Write: Create new research notes
• Edit: Update existing research notes
• Glob: Find research files by pattern
• Grep: Search research content
• WebSearch: Search the web for technical information
• WebFetch: Fetch and analyze web pages

Research Note Structure

Every research note includes:

Copy# Research: <Title>
 
**Date**: YYYY-MM-DD
**Researcher**: [Agent or Name]
**Status**: Active | Superseded | Archived
 
## Summary
[2-3 sentence TL;DR]
 
## Key Findings
1. [Finding with explanation]
2. [Finding with explanation]
3. ...
 
## Recommended Approach
[Which approach is recommended and why]
 
## Implementation Steps
1. [High-level step]
2. [High-level step]
...
 
## Risks & Considerations
- [Risk or trade-off]
- [Risk or trade-off]
 
## Trade-offs
| Option | Pros | Cons |
|--------|------|------|
| A      | ...  | ...  |
| B      | ...  | ...  |
 
## Sources
- [Title](URL) - Retrieved YYYY-MM-DD
- [Title](URL) - Retrieved YYYY-MM-DD
 
## Related
- ADRs: ADR-0001, ADR-0003
- Stories: US-0042, US-0055
- Epics: EP-0002
 
## Notes
[Additional context, caveats, future research needed]

Research Index Format

docs/10-research/README.md maintains a chronological table (newest first):

Copy| Date       | Topic                        | Path                        | Summary                     |
|------------|------------------------------|-----------------------------|-----------------------------|
| 2025-10-16 | JWT authentication patterns  | 20251016-jwt-auth.md        | Compared JWT, session, OAuth2 |
| 2025-10-15 | React state management       | 20251015-react-state.md     | Redux vs Zustand vs Context |

Quality Checklist

Before saving research:

• Date is current (YYYY-MM-DD format)
• Summary is concise (2-3 sentences)
• At least 3 key findings listed
• Recommended approach stated clearly
• Sources cited with URLs and retrieval dates
• Related ADRs/stories/epics linked
• Index updated with newest entry at top
• All external links are to official documentation

Identifying Research Gaps

The Research Agent flags research gaps when:

• Technology choice not yet researched (needed before ADR)
• Approach uncertainty mentioned in story notes
• Multiple approaches discussed without clear winner
• ADR exists but lacks supporting research
• Research is stale (>90 days and tech has changed)
• Duplicate research needed (tech versions updated)

Coordination with Other Agents

Research requests commonly come from:

• AG-UI: Design systems, component patterns, accessibility techniques
• AG-API: API architectures, database designs, auth patterns
• AG-CI: Test frameworks, CI platforms, code quality tools
• AG-DEVOPS: Deployment strategies, container orchestration, monitoring
• ADR-WRITER: Technical alternatives before creating decisions
• EPIC-PLANNER: Technology stack research before planning epics

When research is requested:

1. Check docs/09-agents/bus/log.jsonl for research request message
2. Complete research (web or ChatGPT prompt)
3. Save findings to docs/10-research/
4. Update research index
5. Post bus message to notify requester

ChatGPT Prompt Template

When building research prompt, include:

CopyContext: [Project overview from context.md]
Current priority: [From status.json]
Related ADRs: [List relevant decisions]
 
Research topic: [Specific question]
 
Please provide:
1. TL;DR (2-3 sentences)
2. Step-by-step implementation plan with exact file paths
3. Minimal runnable code snippets (copy-paste ready)
4. Configuration (env vars, config files, CLI flags)
5. Error handling patterns
6. Observability (logging, metrics, tracing)
7. Tests: unit, integration, E2E examples
8. Manual testing checklist
9. Security checklist (auth, input validation, secrets, etc.)
10. Privacy considerations (PII, GDPR, data retention)
11. ADR draft with context, options, recommendation, consequences
12. Story breakdown (3-6 stories with Given/When/Then AC)
13. Rollback plan
14. Risks and gotchas
15. PR body template
16. Sources: official docs/repos only with title, URL, date
 
Final checklist:
- [ ] Ready to paste back to Claude for implementation
- [ ] All code snippets tested conceptually
- [ ] Risks clearly flagged

Related Agents

• documentation - Uses research findings to create guides and docs
• adr-writer - Always requests research before creating ADRs
• epic-planner - Requests tech stack research before planning features
• mentor - May request research to clarify technical questions
• babysit - Can coordinate research requests from other agents

Common Patterns

Two Research Workflows

• Web Research: Direct search and synthesis (faster for straightforward topics)
• ChatGPT Prompt: Build comprehensive prompt for AI to analyze (better for complex decisions)

Research Before Decisions

• Always research before creating ADRs (ADR-WRITER requests research)
• Always research before planning epics (EPIC-PLANNER requests research)
• Flag uncertainty in stories and research before implementation

Stale Research Management

• Quarterly audit of docs/10-research/ for old research
• Mark as "Superseded" if new research contradicts old
• Never delete research (keep for historical context)
• Update if tech versions have changed