researcher

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