Research Workflow

Overview

Research Workflow defines how the researcher agent investigates external context before planning begins and when implementation encounters unknowns. It provides a structured checklist, tool selection priorities, and a gap discovery protocol — ensuring research is systematic rather than ad hoc.

Research Modes

10-Point Checklist

1. Versions & dependencies — current stable releases of your stack
2. Breaking changes — migration guides, deprecated APIs
3. Best practices — recommended approaches from official docs and community
4. Stack documentation — relevant sections via context7 or web search
5. Architectural patterns — reference implementations of similar tasks
6. Compatibility — peer dependency conflicts, runtime compatibility
7. Security advisories — known CVEs in your dependency tree
8. Past experience — relevant lessons from previous tasks (via LTM, if available)
9. Existing codebase — reusable components already in your project
10. Infrastructure constraints — ports, resources, server limits

Lite mode uses checkpoints 1, 3, 4, 6, 9 — focused on what's most likely to cause issues in moderate-complexity tasks.

Tool Selection Priority

The researcher agent adapts to available tools in this order:

1. context7 MCP — token-efficient library documentation (preferred for stack docs)
2. WebSearch — version checks, CVE lookups, community best practices
3. WebFetch — specific documentation pages, release notes
4. Scrutator LTM API — past task experience from long-term memory
5. Codebase tools — always available: grep, glob, read for local analysis

No hard dependencies on any specific tool. Missing tools degrade gracefully — findings from training data are flagged as [unverified].

Gap Discovery Protocol

When the developer agent hits an unknown during /dr-do:

1. Trigger — import failure, unexpected API behavior, documentation mismatch, missing dependency
2. Spawn — researcher subagent with focused query about the specific gap
3. Investigate — targeted research using available tools
4. Record — append findings to the insights document's "Gap Discoveries" section
5. Assess — is the gap solvable or fundamental?
6. Resume or escalate — solvable gaps return to implementation; fundamental gaps (wrong technology, impossible requirement) STOP and recommend returning to /dr-prd

Output Format

Results go into datarim/insights/INSIGHTS-{task-id}.md with 7 sections:

• Stack & Versions
• Best Practices
• Documentation References
• Existing Codebase
• Risks & Compatibility
• LTM Context
• Gap Discoveries (grows during implementation)

Only relevant sections are filled. Each finding includes its source. Findings based on training data are marked [unverified].