/research

name: research
description: "Answer one cited question on code, history, claims or patterns. Use when: asked how it works, why it changed, if a claim or done/shipped report holds, or a pattern warrants a rule."
practices:
- pragmatic-programmer
- ddd-bounded-context
- evidence-based-engineering
hexagonal_role: driving-adapter
consumes:
- research-question
- native-source-evidence
produces:
- research-report
- codebase-recon.v1
- pattern-mining.v1
- reality-check-report.v1
- goal-measurement-report
- native-status-snapshot
context_rel:
- kind: supplier-to
  with: plan
skill_api_version: 1
user-invocable: true
metadata:
  capabilities: [research, codebase_recon, pattern_mining, compare_claim_to_evidence, measure_declared_goals, report_native_status]
  effects: [write_research_report, write_recon_pack, write_pattern_evidence, write_advisory_gap_report, write_goal_snapshot, write_requested_rendered_spec]
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  dependencies: []
  triggers: ["holds up", "really done"]
output_contract: cited answer; findings.json for ordinary durable reports; validated codebase-recon.v1, pattern-mining.v1 or reality-check-report.v1 for selected evidence modes; per-item claim ledger with no verdict

Research

Answer the caller's bounded question with cited evidence. Choose ordinary investigation, claim checking, a claimed-state audit, decision lineage, repository tracing or pattern evidence according to the question; these are optional modes, not a sequence. A quick answer needs no report file. [Plan](../plan/SKILL.md) owns unified discovery and resumption when the question is part of shaping a change; return this cited answer to that existing intent without restarting its interview or taking over caller choices.

Evidence rules

• **One lineage counts once.** Copies, ports and repeated quotations of one

upstream source are a single exemplar, however many files or reports carry them. Check provenance before counting instances as independent, and stop searching once new queries return only sources already read.

• **Separate the invariant from the incidental.** Align instances by their role

in the behavior; name what must hold, what legitimately varies and what is incidental syntax. An instance missing the invariant is not an instance.

• **Recurrence does not earn a gate.** A blocking check needs a demonstrated

cost of violation: an incident, defect or measured harm traced to the pattern's absence. Recommend the least committed useful shape: no action, a reference or checklist line, a template, a helper, and only then a gate.

• **Thin evidence stays a hypothesis.** Fewer than three independent exemplars,

or no passing holdout, leaves a pattern a hypothesis; say what evidence would confirm or refute it.

• Keep observation, inference, contradiction and unknown separate. Every

material claim cites evidence; a claim taken from a document or report cites a passage that asserts it, not one that only discusses the topic, else mark it unsupported. Say when a decisive claim rests on one source; agreement does not erase shared provenance.

• **A call is not the callee's behavior.** Seeing code call `retry`, `validate`

or a service shows only that the call happens. Before a claim relies on what the callee guarantees (retried, atomic, idempotent, ordered, durable), read its implementation or tests, or an external service's published contract; otherwise mark the guarantee unknown in the claim itself, not in a later caveat.

• **A search that found nothing proves absence only if it could have matched.**

Before saying something does not exist or is unused, check the search's exit status and error output, whether results were truncated, whether ignore rules or default filters skipped relevant paths (ignored, hidden, vendored or generated files), and that the intended ref or tree was searched rather than a stale index. Where cheap, confirm the same search finds a term known to be present. A failed or mis-scoped search is an unknown with its cause, not "none found". For "unused" or "nothing calls this", text search also misses re-exports, aliases, reflection, string-keyed dispatch, dependency injection, generated code and outside consumers; prefer the host's references-aware tool when it has one, and name which of these remain unchecked.

Investigation

1. State the question and the decision it informs. Reuse the accepted scope and identify what evidence would answer it; do not expand the objective mid-search. Use the subject, range and sources the caller named. Report an empty range, a missing subject or an unreachable named source as such instead of answering about an adjacent one; name any substitute the caller allowed. 2. Inspect the smallest relevant sources and verify search hits against the actual source. External facts that change (versions, vendor behavior, standards) need current primary sources, through the host's web tools when available and permitted; otherwise mark the claim unknown and name the source that would settle it. Before a query leaves the host, strip host names, IP addresses, file paths, query fragments, account or customer identifiers and internal names, and search on the generic error class with the library and version; if no safe form remains, skip the lookup and say so. For how a third-party library, tool or service behaves here, answer from the version this repository resolves (lockfile, installed binary's version or vendored copy) and that version's source, tests or release notes; latest docs, web answers and recall are leads, so say when they describe another version. Before recommending an external API, SDK, auth scope or service, check deprecation, sunset and breaking-change notices for that version and state any, or say that status is unchecked. 3. Lead with the answer, then show evidence and remainin