Deep Research Skill

Systematic methodology for autonomous comprehensive research. This skill transforms any task into a research-backed, SOTA-optimized implementation by following a structured protocol.

When This Skill Activates

This skill supplements the always-on auto-research instruction with detailed methodology for complex research scenarios:

Architecture decisions (new system, major refactor, technology choice)
Technology evaluations (comparing libraries, frameworks, approaches)
Migration planning (version upgrades, library swaps, architectural shifts)
Complex debugging (unfamiliar errors, subtle issues, environment-specific bugs)
Best practices audit (security, performance, accessibility, SEO)
Prior art search (has someone solved this before? how?)

Phase 1 — Scope & Strategy (Before Searching)

1.1 Decompose the Task

Break the request into atomic research questions:

## Research Questions
- Q1: What is the SOTA approach for [specific problem]?
- Q2: What are the known pitfalls/anti-patterns?
- Q3: What version/compatibility constraints exist?
- Q4: Are there existing implementations to reference?

1.2 Identify Search Domains

Map each question to the most relevant sources:

Question Type	Primary Sources	Secondary Sources
"How to" / Implementation	Official docs, GitHub examples	Community blogs, SO answers
"Best practice" / Pattern	Framework guides, GitHub discussions, awesome-lists	Conference talks, expert blogs
"Bug / Issue"	GitHub issues, SO, framework changelogs	Community forums, Discord
"Compare" / Evaluate	npm trends, GitHub stars/activity, benchmarks	Blog comparisons, Reddit threads
"Security" / Vulnerability	CVE databases, security advisories, official docs	OWASP guides, security blogs
"Architecture" / Design	ADRs in open-source repos, framework docs	Martin Fowler, thoughtworks radar

1.3 Define Search Keywords

Generate 3-5 search query variants per question using:

Exact terms: "TanStack Query v5" suspense streaming
Alternations: nextjs|next.js "app router" caching|cache
Error-specific: paste exact error message + framework version

Phase 2 — Parallel Research Execution

2.1 Codebase Scan (Always First)

1. grep_search / semantic_search for related patterns in workspace
2. Check package.json / lock files for pinned versions
3. Read existing implementations of similar features
4. Check project conventions (AGENTS.md, instructions, README)

2.2 Web Research (Parallel Batches)

Launch 2-4 parallel web/fetch calls per batch:

Batch 1 — Official Sources:

Framework/library official docs (latest version matching project)
GitHub repository README, CHANGELOG, migration guide
Official blog posts / announcements

Batch 2 — Community Sources:

GitHub Issues/Discussions (filter: open + closed, sort by reactions)
Stack Overflow (tagged questions, sort by votes)
awesome-* lists for the technology

Batch 3 — Deep Dive (if needed):

Specific GitHub repos implementing the pattern
npm/registry package comparisons
Blog posts from recognized experts
Conference talk summaries

2.3 Source Quality Checklist

For each source found, quickly assess:

Date: Published within last 6 months? (if older, is the info stable/version-independent?)
Version: Matches project's pinned versions? (reject v4 guides when project uses v5)
Authority: Official docs > maintainer comments > expert blogs > random posts
Validation: Can the claim be cross-referenced with at least one other source?
Completeness: Does it address edge cases, not just happy path?

Phase 3 — Synthesis & Enrichment

3.1 Cross-Reference Matrix

For conflicting information, build a decision matrix:

| Approach  | Source 1 (docs) | Source 2 (GitHub) | Source 3 (blog) | Verdict     |
| --------- | --------------- | ----------------- | --------------- | ----------- |
| Option A  | ✅ Recommended  | ⚠️ Works but...  | ✅ Preferred    | → Use this  |
| Option B  | ❌ Deprecated   | ✅ Still works    | ❌ Anti-pattern | → Avoid     |

3.2 Enrichment Checklist

After research, enrich the original request with:

Missing requirements the user didn't consider (edge cases, error handling, a11y)
SOTA patterns discovered during research (better alternatives to naive approach)
Anti-patterns to explicitly avoid (with source citation)
Version-specific gotchas for the project's stack
Performance implications of the chosen approach
Security considerations if applicable
Testing strategy informed by common failure modes found in issues

3.3 Synthesis Output Format

Before implementing, briefly present findings:

## Research Findings

**Approach**: [chosen approach with 1-sentence justification]
**Key Sources**: [2-3 most authoritative sources with URLs]
**Enrichments**: [what was added beyond the original request]
**Risks**: [any gotchas or limitations discovered]

Keep this short (5-10 lines max). The user wants implementation, not a thesis.

Phase 4 — Implementation Integration

4.1 Apply Findings

Implement using the SOTA approach identified in research
Add inline comments citing sources for non-obvious decisions: // Ref: https://... — avoids hydration mismatch
Apply discovered anti-pattern avoidance proactively
Include error handling for edge cases found in issue trackers

4.2 Post-Implementation Validation

Verify implementation matches the approach described in official docs
Check for version-specific behaviors (breaking changes, deprecated APIs)
If available, run tests to confirm the approach works

Common Research Templates

Template: Library/Framework Feature

1. Check official docs for [feature] in [version]
2. Search GitHub issues: "[feature] [version]" label:bug|enhancement
3. Check CHANGELOG for breaking changes since [version]
4. Find usage examples in popular repos

Template: Bug Investigation

1. Search exact error message in GitHub issues
2. Check if fixed in newer version (CHANGELOG)
3. Search Stack Overflow with error + framework version
4. Check if related to known breaking change

Template: Architecture Decision

1. Search ADRs in reference architectures (GitHub)
2. Check official framework recommendations
3. Compare approaches in popular open-source projects
4. Read expert analysis (ThoughtWorks Radar, Martin Fowler, etc.)
5. Check community consensus (Reddit, Discord, Discussions)

Template: Technology Comparison

1. npm trends / star history (activity != quality, but stale = risk)
2. Bundle size comparison (bundlephobia)
3. Official docs quality and completeness
4. GitHub issues: response time, community health
5. Migration path from current tool

Anti-Patterns to Avoid

❌ Research paralysis — don't spend 10 min researching a 30-second fix
❌ Source dumping — don't paste raw research at user; synthesize
❌ Outdated confidence — don't trust a 2022 guide for a tool on v5 when project uses v8
❌ Single source — never base architectural decisions on one blog post
❌ Ignoring codebase — always check existing patterns first; consistency > theoretical best
❌ Over-researching — 3 quality sources beat 15 mediocre ones

deep-research