research-method

name	research-method
description	Applies a disciplined research method to conceptual, definitional, and "difference between X and Y" questions — especially overloaded terms and LLM/agent-domain topics, where answering from memory is a known trap. Use when asked to explain or compare concepts, define a term spanning multiple communities/lineages (e.g. "sensor", "hook", "agent"), or when the user demands primary sources. Also trigger when a question names Claude, Anthropic, or any agent-engineering concept with the provider unstated. Surfaces competing definitions first, checks the local repo/config before the literature, fetches and quotes primary sources instead of trusting search snippets, and says explicitly when the canon is unsettled instead of forcing false symmetry. Not for Claude API/model reference lookups (pricing, params, context windows, model IDs) — use claude-api for those. Not for code-writing, and not a generic web-search wrapper; skip when a single canonical source is already known and correctly cited.
allowed-tools	Read Grep Glob WebSearch WebFetch
license	CC-BY-4.0
status	unstable
metadata	{"author":"Leandro Kellermann de Oliveira <[e-mail]>","version":"0.1.0","model":"sonnet"}

Research Method

Answers conceptual and terminology questions credibly. The goal is a verifiable answer, not a confident one. Follow these five steps in order before writing the answer.

Step 1 — Enumerate lineages for overloaded terms

Before answering, check whether the term or concept means different things in different communities (e.g. "sensor" and "hook" mean one thing in data-orchestration tools like Airflow and a different thing in agent harnesses). If it does:

• Name the competing definitions up front, state which one you're using, and why — or ask the user to confirm the lineage before going further.
• Do not silently pick one and answer as if it were the only meaning. A wrong guess here wastes the entire answer, not just one sentence of it.

Step 2 — Survey the local artifact before the literature

Check what's already in front of you — this repo, the existing config, the half-built thing — before researching the field externally. Use Read/Grep/Glob first.

• The local artifact is a primary source, and the cheapest one to check. A question that looks like "design X from scratch" often collapses to "formalize what's already here" once you've looked.
• Don't assume greenfield. Greenfield assumptions are the most expensive kind of wrong, because they invalidate the whole framing of the answer, not just one fact in it.

Step 3 — Ground in primary sources; fetch, don't trust snippets

For anything outside the local repo, use WebSearch to find the source, then WebFetch the actual primary document and quote it directly — don't answer from a search snippet or an aggregator/Medium summary, and don't answer an LLM/Claude/Anthropic-shaped question from training memory.

• Quote precise sentences and attribute them to the named author or vendor doc.
• Don't state ecosystem facts (version numbers, standards-body status, pricing) from memory — confirm them against the primary page, every time, even if you're confident.

Step 4 — Say so when the canon is unsettled

Not every pair or set of terms has a clean, symmetric answer. One term in a comparison may be well-defined (a vendor has a canonical doc for it) while the other is emerging or contested across multiple authors. When that's the case, say so explicitly rather than forcing a tidy dichotomy that doesn't actually exist yet. Naming the asymmetry is more useful than a clean answer that overstates consensus.

Step 5 — Design the output for its actual consumer

Before finalizing the answer, decide who consumes it and shape it accordingly — a human reading prose wants the lineage/sources framing above; a fresh subagent or automated caller needs a self-contained spec, not a narrative (see subagent-handoffs for that pattern). Don't default to one shape for every consumer.

Output convention

Close the answer with a Sources: section listing each primary document fetched and quoted, attributed by author/vendor. If a claim came from local repo survey (Step 2) rather than an external fetch, say so instead of inventing a citation.

Example: sensors vs. hooks (agent-harness sense)

User asked for the difference between "sensors" and "hooks" in AI engineering, demanding authoritative sources. The terms span two lineages:

• Data-orchestration (Airflow): sensor = an operator that waits for a condition; hook = a reusable connection interface. Both are concrete classes; hooks power sensors.
• Agent harnesses: hook = a deterministic lifecycle interception point (Anthropic's Claude Code hooks doc); sensor = an observation/feedback mechanism for self-correction (Böckeler's "Harness engineering" article; Russell & Norvig's perception-channel framing).

Both lineages were surfaced before answering; the user then clarified they meant the agent-harness sense. Because the lineages were named up front, the correction cost one sentence, not a rewrite (Step 1). The dichotomy is clean in Airflow but not in agent engineering — "hook" is well-defined, "sensor" is still emerging — so that asymmetry was stated rather than smoothed over (Step 4). Sources were fetched and quoted directly from Anthropic's docs and Böckeler's article, not summarized from search results (Step 3).

Error handling

If WebFetch fails or a primary source is paywalled/unreachable, don't fall back to memory or a secondary summary silently — tell the user the primary source couldn't be fetched, name what you found instead (e.g. an aggregator snippet), and flag it as lower-confidence rather than presenting it as equivalent to a verified primary citation.

Out of scope

• Claude API/model reference lookups (pricing, parameters, context windows, model IDs) — defer to the claude-api skill.
• Code-writing or implementation tasks.
• Generic "do a web search for me" requests with no conceptual/definitional question attached.
• Questions where a single canonical source is already known and already correctly cited in the conversation — re-researching it adds no value.