Use when the user wants structured investigation of a technical topic with a reusable artifact and evidence-backed recommendations
Run a structured research workflow for a user-supplied topic, ground it in the current project, write a reusable research artifact, and optionally propose ADRs from the findings.
Primary artifact: docs/research/YYYY-MM-DD-{topic}.md
Do not use for retrospective review of commits. Use ago-audit for that.
Require a topic.
If the user did not provide one, ask:
What topic would you like to research?
Once provided, derive a kebab-case slug for filenames.
Read, when present:
README.mdCLAUDE.mddocs/adr/ or docs/decisions/docs/research/Capture:
Draft 3 to 5 concrete research questions that are:
Present the plan before starting research:
Wait for the user's approval or edits. Do not begin research until the plan is confirmed.
For each approved question, combine whatever methods are available:
For every factual claim, record a source:
Rate confidence as HIGH, MEDIUM, or LOW.
If something cannot be answered well, record the gap instead of guessing.
Write:
docs/research/YYYY-MM-DD-{topic-slug}.md
Include:
Set status to:
Complete if all questions were answered with at least medium confidencePartial otherwiseWrite the artifact without asking for another confirmation. This file is the primary output of the skill.
If the research reveals architecture or long-term product decisions that should be formalized, propose ADR candidates to the user.
Only write ADRs after approval.
If approved:
docs/adr/docs/adr/README.md only if it already existsIf the research produced actionable recommendations, offer a planning handoff that references:
Use the same handoff shape as the Claude workflow:
If the user declines, stop with artifacts on disk.
docs/research/YYYY-MM-DD-{topic-slug}.mddocs/adr/{NNN}-{title}.md