Research
Turn a technical question into a decision you can defend: evidence from primary sources, a cited comparison, and a recommendation that states its own uncertainty. The output feeds an RFC or ADR; it is not the decision document itself. Depth is proportional to the blast radius of the decision, not to how much you could read.
The loop
- Frame the question and the criteria. Pin down the decision this feeds and the axes that will matter (performance, DX, bundle size, maintenance, license, lock-in, team familiarity — whichever apply). Those axes become the columns of the matrix. If the question is too broad to answer (no budget, scale, or constraint), ask one or two clarifiers and stop; a vague question yields a vague matrix.
- Go to primary sources. Prefer official docs, specs, changelogs, benchmarks, and the source itself over blog posts and SEO content. Read the repo's own constraints too (existing deps, runtime, team). Date volatile facts — ecosystem claims rot.
- Capture evidence, cite as you go. Each finding is a claim plus where it came from. Separate what the source says from your inference. Keep a short trail of sources kept and dropped, with the reason, so the evidence is auditable.
- Surface contradictions, do not smooth them. When sources conflict, say so explicitly and say which you trust and why. What you cannot resolve becomes an open question, not a silent pick.
- Build the decision matrix. Options as rows (always include "do nothing / defer"), the criteria from step 1 as columns. Fill cells with cited evidence, not impressions.
- Recommend with uncertainty. State the recommendation, your confidence, what would change it, and what remains unknown. Do not overstate a thin evidence base.
- Hand off. The matrix and recommendation are the input to /rfc (Options, Trade-offs) or /adr (Alternatives Considered). Stop there — research is not the decision doc.
Rules
- Primary sources over secondary. Cite every load-bearing claim; date the volatile ones.
- Not a literature review and not a full research-report harness: bound the search to what the decision needs.
- Flag uncertainty explicitly; keep contradictions visible rather than resolving them by omission.
- No marketing prose, no false confidence. A recommendation the evidence does not support is worse than "we don't know yet, here is how to find out".
Output
A short research brief: the question and criteria, the decision matrix (options x criteria, cells cited), the key findings with citations, the contradictions and gaps, and a recommendation with an explicit confidence level and what would change it. End with the handoff: which decision doc this feeds (/rfc or /adr) and the one-line framing for it. English prose, no em dashes, per persona.
1---2name: research-23description: Research4---56# Research78Turn a technical question into a decision you can defend: evidence from primary sources, a cited comparison, and a recommendation that states its own uncertainty. The output feeds an RFC or ADR; it is not the decision document itself. Depth is proportional to the blast radius of the decision, not to how much you could read.910## The loop11121. **Frame the question and the criteria.** Pin down the decision this feeds and the axes that will matter (performance, DX, bundle size, maintenance, license, lock-in, team familiarity — whichever apply). Those axes become the columns of the matrix. If the question is too broad to answer (no budget, scale, or constraint), ask one or two clarifiers and stop; a vague question yields a vague matrix.132. **Go to primary sources.** Prefer official docs, specs, changelogs, benchmarks, and the source itself over blog posts and SEO content. Read the repo's own constraints too (existing deps, runtime, team). Date volatile facts — ecosystem claims rot.143. **Capture evidence, cite as you go.** Each finding is a claim plus where it came from. Separate what the source says from your inference. Keep a short trail of sources kept and dropped, with the reason, so the evidence is auditable.154. **Surface contradictions, do not smooth them.** When sources conflict, say so explicitly and say which you trust and why. What you cannot resolve becomes an open question, not a silent pick.165. **Build the decision matrix.** Options as rows (always include "do nothing / defer"), the criteria from step 1 as columns. Fill cells with cited evidence, not impressions.176. **Recommend with uncertainty.** State the recommendation, your confidence, what would change it, and what remains unknown. Do not overstate a thin evidence base.187. **Hand off.** The matrix and recommendation are the input to /rfc (Options, Trade-offs) or /adr (Alternatives Considered). Stop there — research is not the decision doc.1920## Rules2122- Primary sources over secondary. Cite every load-bearing claim; date the volatile ones.23- Not a literature review and not a full research-report harness: bound the search to what the decision needs.24- Flag uncertainty explicitly; keep contradictions visible rather than resolving them by omission.25- No marketing prose, no false confidence. A recommendation the evidence does not support is worse than "we don't know yet, here is how to find out".2627## Output2829A short research brief: the question and criteria, the decision matrix (options x criteria, cells cited), the key findings with citations, the contradictions and gaps, and a recommendation with an explicit confidence level and what would change it. End with the handoff: which decision doc this feeds (/rfc or /adr) and the one-line framing for it. English prose, no em dashes, per persona.
yuri-semenenko