Research Way¶

Source: hooks/ways/research/research.md

Frontmatter

Field	Value
`description`	Structured investigation — scoping a question, fanning out across independent sources, ranking source authority from official docs down to community posts, and synthesizing findings into an answer
`vocabulary`	`research investigate look into dig into find out compare evaluate assess synthesize source sources primary source official docs authority credible trust citation evidence survey landscape alternatives options fan-out sweep confidence`
`refire`	`0.15`
`macro`	`append`
`scope`	`agent`
`requires`	`['Bash(grep:*)']`

Define the Question¶

Before searching, state what you're trying to learn and why. A vague "research X" becomes "I need to understand X to decide between Y and Z." The user may not have articulated this — help them sharpen it.

Investigation Structure¶

Scope — What's in bounds? What would be a tangent?
Gather — Use tools (WebSearch, WebFetch, Grep, Read) to collect information. Prefer primary sources over summaries of summaries. When the question spans several independent sources, asking for the research is asking for the sweep: fan Explore or general-purpose agents across them rather than pausing to request permission, and say why in a clause ("six independent sources; agents return conclusions, not page dumps"). Deep-research and Workflow are not covered by that — propose those and discuss. See ADR-175. Put four rules in every fan-out brief:
Say "not found" rather than guess.
Every claim carries a file path or URL and an exact value (version, port, name).
Sample rather than bulk-read: name the manifests, entry points, and config files to start from.
End with what was deliberately omitted, so you can ask for it.
Evaluate — Not all sources are equal. Rank them: official docs for the exact version in use, then upstream source, then migration guides and advisories, then community posts, then LLM-generated content. Flag confidence levels.
Synthesize — Compress findings into a structure the user can act on. Don't dump raw results.
Present — Lead with the answer, then the evidence. The user wants the conclusion first.

Comparative Analysis¶

When comparing options (tools, approaches, vendors, libraries):

Column	Purpose
Option	What's being compared
Strengths	What it does well
Weaknesses	Where it falls short
Fits when	The scenario where this option wins
Avoid when	The scenario where it's wrong

End with a recommendation. Don't just present a neutral table — defend a choice based on the user's context.

Source Discipline¶

Distinguish what you know (training data) from what you found (tool results) from what you inferred.
When citing web results, include the URL so the user can verify.
If you can't find reliable information, say so. "I couldn't find authoritative sources on X" is more useful than hedging.
Stale information is worse than no information. Check dates on sources.

When Research is Overkill¶

Not every question needs a structured investigation. If the answer is in the codebase, read the code. If it's a factual recall question, just answer it. This way is for genuine unknowns that require gathering and synthesis.