Researcher
Overview
A structured research workflow that searches the web for solutions to a problem, organizes findings into a dedicated directory, tests each candidate solution, and documents results.
When to Use
- User asks to "research X", "find solutions for X", or "investigate X"
- Problem requires searching multiple sources on the internet
- User wants organized, documented findings rather than a quick answer
Core Pattern
After completing each step, pause and ask the user to confirm before proceeding to the next step.
Step 1 — Create Problem Directory
mkdir <problem_name>_problem/
Use snake_case. Keep it short and descriptive.
→ Confirm with user before proceeding.
Step 2 — Search for Solutions in Parallel
Dispatch multiple subagents (model: claude-sonnet-4-6) — one per search angle. Each subagent:
- Searches the web for candidate solutions
- Returns: solution name, summary, source URLs, and page location/section
- Sources to cover:
- Community: Stack Overflow, Reddit, Hacker News, dev.to
- Articles: Medium, InfoQ, DZone
- Code: GitHub, Papers With Code, npm/PyPI/crates.io package pages
- Academic: arXiv, Google Scholar, ResearchGate, Semantic Scholar, IEEE Xplore, ACM Digital Library, USENIX, Distill.pub
- Reference: official docs, tutorials, Wikipedia
- Video: YouTube conference talks (NeurIPS, ICML, OSDI, CCC, etc.)
Present the list of solutions found to the user.
→ Confirm with user before proceeding (user may exclude solutions).
Step 3 — Create a Directory per Solution
For each candidate solution, create:
<problem_name>_problem/
solution_<solution_name>/
README.md
documentation/
Step 4 — Gather Documentation per Solution
For each solution, dispatch one subagent (model: claude-sonnet-4-6) per source category in parallel:
- Community: Stack Overflow, Reddit, Hacker News, dev.to
- Articles: Medium, InfoQ, DZone
- Code: GitHub, Papers With Code, npm/PyPI/crates.io
- Academic: arXiv, Google Scholar, ResearchGate, Semantic Scholar, IEEE Xplore, ACM Digital Library, USENIX, Distill.pub
- Reference: official docs, Wikipedia
- Video: YouTube conference talks (NeurIPS, ICML, OSDI, etc.)
For each document found, create a file inside documentation/:
documentation/
<doc_topic>.md
Each <doc_topic>.md contains:
# <Document Title>
## Source
- URL: <url>
- Page section / heading: "<where on page>"
## Summary
Key information found on this page relevant to the solution.
Step 5 — Document Each Solution
Each README.md contains:
# Solution: <Solution Name>
## Summary
One-paragraph description of the approach.
## Sources
- [Title](URL) — section: "heading or paragraph where found"
## Pros
- ...
## Cons
- ...
→ Ask the user: "Do you want to test each solution, or compare them based on documentation only?"
- If yes, test → proceed to Step 6
- If no, skip testing → go directly to Step 7 (Decision Summary uses documentation and README only)
Step 6 — Test Each Solution (only if user confirmed testing)
Spawn one subagent (model: claude-sonnet-4-6) per solution — sequentially, one at a time. Each subagent independently attempts an implementation or reproduction of its assigned solution, then writes test_results_<solution_name>.md. Wait for each subagent to complete before spawning the next.
# Test Results: <Solution Name>
## Test Description
What was tested and how.
## Steps Taken
1. ...
2. ...
## Outcome
- [ ] Works as documented
- [ ] Partially works (describe limitations)
- [ ] Failed (describe errors)
## Errors / Issues Encountered
Paste relevant error messages or unexpected behavior.
## Verdict
Short assessment: recommended / conditional / avoid — and why.
Step 7 — Decision Summary (model: claude-opus-4-6)
After all solutions are tested, create decision/ inside the problem directory:
<problem_name>_problem/
solution_<name_a>/
README.md
documentation/
<doc_topic>.md
test_results_<name_a>.md
solution_<name_b>/
README.md
documentation/
<doc_topic>.md
test_results_<name_b>.md
decision/
DECISION.md
Before writing DECISION.md, define:
1. Decision Aspects — derive from the problem context. Examples:
- Ease of implementation
- Performance
- Community support
- Documentation quality
- Test result (works / partial / failed)
- Maintenance burden
- Security
- Cost / dependencies
2. Scoring Method — score each aspect per solution:
| Score | Meaning |
|---|---|
| 3 | Excellent |
| 2 | Good |
| 1 | Poor |
| 0 | Fails / N/A |
Each aspect may have a weight (1–3) reflecting its importance for this problem. Weighted score = score × weight.
DECISION.md contains:
# Decision: <Problem Name>
## Scoring Aspects & Weights
| Aspect | Weight |
|--------|--------|
| Ease of implementation | 2 |
| Performance | 3 |
| Documentation quality | 2 |
| Test result | 3 |
| Community support | 1 |
| ... | ... |
## Scoring Table
| Aspect (weight) | solution_a | solution_b | solution_c |
|-----------------|-----------|-----------|-----------|
| Ease of impl. (×2) | 3 → 6 | 2 → 4 | 1 → 2 |
| Performance (×3) | 2 → 6 | 3 → 9 | 1 → 3 |
| Test result (×3) | 3 → 9 | 2 → 6 | 0 → 0 |
| Community (×1) | 2 → 2 | 3 → 3 | 2 → 2 |
| **TOTAL** | **23** | **22** | **7** |
## Solutions Overview
| Solution | Works? | Pros | Cons |
|----------|--------|------|------|
| solution_a | ✅ Yes | ... | ... |
| solution_b | ⚠️ Partial | ... | ... |
| solution_c | ❌ No | ... | ... |
## Final Decision
**Chosen solution:** `solution_a` (score: 23/max)
### Why
Explanation covering score breakdown, trade-offs, and fit for the problem.
### How to Apply
Brief guidance on using the chosen solution.
→ Present the decision and scoring table to the user and confirm.
Quick Reference
| Step | Action | Model | Confirm? |
|---|---|---|---|
| 1 | mkdir <problem>_problem/ | — | Yes |
| 2 | Parallel subagents — search (docs, tutorials, GitHub, Medium, Reddit, SO) | Sonnet | Yes (user may exclude) |
| 3 | mkdir solution_<name>/ + documentation/ per solution | — | — |
| 4 | Parallel subagents — gather docs into documentation/<topic>.md | Sonnet | — |
| 5 | Write README.md with summary, sources, pros/cons | — | Yes |
| 6 | Sequential subagents — test each solution, write test_results_<name>.md | Sonnet | — |
| 7 | Create decision/DECISION.md with comparison table and final decision | Opus | Yes |
Common Mistakes
- Single search query: Use multiple angles (official docs, tutorials, Stack Overflow, GitHub issues)
- Missing source location: Always note the section/heading where info was found, not just the URL
- Skipping tests: Every solution must be tested — no untested verdicts
- Vague test results: Document exact errors, commands run, and environment details