<quick_start> When researching code, follow the tool escalation ladder:

1. •Local first - Use Grep/Glob/Read for codebase exploration
2. •Terminal research - Use fast CLI tools (w3m/lynx, curl, jq, rg, fd) and DDG bangs
3. •Built-in web - Use WebSearch/WebFetch for documentation and articles
4. •Scripts - Use API scripts for GitHub, Stack Overflow
5. •MCP servers - Use Exa/Deepwiki/Chrome for complex research needs

Start simple. Escalate only when simpler tools fail. </quick_start>

<tool_hierarchy> <tier name="1" label="Built-in Tools (Use First)"> Local codebase exploration:

• •Grep - Search for patterns, function names, error messages in code
• •Glob - Find files by pattern (e.g., **/*.ts, **/config.*)
• •Read - Read specific files once you know what to look at
• •Task with subagent_type=Explore - For open-ended codebase exploration

Web research:

• •WebSearch - General web search for docs, tutorials, discussions
• •WebFetch - Fetch and analyze specific URLs (works for most static sites)

When to use: Always start here. These tools are fast, low-cost, and handle 80% of research tasks. </tier>

Fallback to POSIX tools:

• •grep, find, sed, awk, cut, sort, uniq

Terminal web/doc workflows:

• •w3m / lynx for fast doc browsing
• •DuckDuckGo bangs (!gh, !so, !npm, !pypi) to jump directly to sources
• •curl + jq + rg for structured data and targeted extraction
• •pup/htmlq/python -m bs4 for HTML parsing when needed
• •readability-lxml (or python -m readability) to clean article content
• •csvkit / xsv for CSV docs and tables
• •fzf to interactively select snippets and URLs
• •Clipboard handoff: pbcopy (macOS) / xclip -selection clipboard (Linux)

Rate-limit hygiene:

• •curl --retry 3 --retry-delay 2 --compressed + backoff (sleep)
• •Use ETag/If-Modified-Since to avoid refetching unchanged docs

When to use: Quick web/CLI research before WebSearch, or when you need high-throughput data extraction. </tier>

github-api.sh - GitHub repository information

# Get repo info, issues, PRs, code search
~/.claude/skills/code-research/scripts/github-api.sh repo owner/repo
~/.claude/skills/code-research/scripts/github-api.sh issues owner/repo "search query"
~/.claude/skills/code-research/scripts/github-api.sh search "code query" language:python

stackoverflow-api.sh - Find solutions to errors

# Search Stack Overflow for solutions
~/.claude/skills/code-research/scripts/stackoverflow-api.sh "error message or question"

When to use: When you need structured API data (issues, PRs, code across repos) that WebSearch can't provide cleanly. </tier>

Deepwiki MCP - Documentation and wiki content

• •Use for: Library documentation, API references, technical wikis
• •Better than WebFetch for structured documentation extraction

Chrome Web Tools MCP - Headless browser automation

• •Use for: JavaScript-heavy sites, sites requiring authentication, dynamic content
• •Example: Navigating https://codewiki.google/github.com/anomalyco/opencode

When to use: When simpler tools fail—JS-rendered content, semantic search needs, or complex documentation sites. </tier> </tool_hierarchy>

<research_workflow> <step name="1" label="Understand the Query"> Classify the research type:

• •Codebase understanding - How does this code work? What's the architecture?
• •Library/API research - How do I use this library? What are the patterns?
• •Bug investigation - Why is this error happening? How do others solve it?
• •Pattern discovery - How do other projects implement X? </step>

Search for patterns

Grep: "functionName|className|errorMessage"

Deep exploration

Task(subagent_type=Explore): "Find how authentication is implemented"

</step>

<step name="2.5" label="Terminal Research">
Use fast terminal tools to browse docs and extract data:

Quick doc browsing

w3m https://docs.example.com/guide

DDG bangs

WebSearch: "!gh repo:org/project authentication middleware"

Fast extraction

curl -s https://docs.example.com/api | rg -n "endpoint" | sed -n '1,120p'

Structured data

curl -s https://api.github.com/repos/org/repo | jq -r '.description'

Clean article text

curl -s https://blog.example.com/post | python -m readability | rg -n "API" | sed -n '1,80p'

CSV extraction

curl -s https://docs.example.com/table.csv | xsv select 1,3 | xsv table | sed -n '1,40p'

Interactive selection

curl -s https://docs.example.com/api | rg -n "endpoint" | fzf

Clipboard handoff

curl -s https://docs.example.com/api | pbcopy # or: xclip -selection clipboard

Prefer Rust utilities when available (rg/fd/bat/sd/xsv); fall back to standard Unix tools otherwise.
</step>

<step name="3" label="Expand to Web">
If local exploration isn't enough:

General search

WebSearch: "library-name how to implement X"

Fetch specific docs

WebFetch: "https://docs.library.com/guide"

</step>

<step name="4" label="Use Scripts for Structured Data">
When you need GitHub/StackOverflow data:
```bash
# Find similar issues
~/.claude/skills/code-research/scripts/github-api.sh issues facebook/react "useEffect cleanup"

# Find error solutions
~/.claude/skills/code-research/scripts/stackoverflow-api.sh "React useEffect memory leak"

Documentation extraction (Deepwiki)

mcp__deepwiki__read_wiki_contents: "react/react" mcp__deepwiki__read_wiki_structure: "anomalyco/opencode" mcp__deepwiki__ask_question: "What are the context engineering strategies used by anomalyco/opencode?"

Website Navigation

Use chrome-devtools-mcp to open up webpages and crawl through them for deeper information extraction tasks.

</step>

<step name="6" label="Synthesize Findings">
Combine findings from all sources:
- Cross-reference information across sources
- Identify consensus patterns vs. edge cases
- Note version-specific information (library versions matter!)
- Cite sources when presenting findings
</step>
</research_workflow>

<output_formats>
Adapt output to the query:

**Quick answer** - For simple questions, respond inline with sources
**Structured summary** - For broader research:
```markdown
## Findings
- Key finding 1
- Key finding 2

## Recommendations
- Recommended approach with rationale

## Sources
- [Source 1](url)
- [Source 2](url)

Research report - For deep dives, create a markdown file:

Write: research-{topic}-{date}.md

</output_formats>

<tool_selection_heuristics>

<anti_patterns> <pitfall name="mcp_first"> Don't reach for MCP servers immediately. Try built-in tools and scripts first—they're faster and use less context. </pitfall>

<success_criteria> Research is complete when:

• •Query is fully answered with supporting evidence
• •Multiple sources consulted when appropriate
• •Tool selection followed the escalation ladder (simplest first)
• •Findings are synthesized, not just listed
• •Sources are cited for traceability
• •Output format matches query complexity </success_criteria>