--- name: research-it description: > Research a technical or product question before building — APIs, libraries, prior art in-repo, external docs, tradeoffs, and a recommendation. Use when the user says "research it", asks what to use, compares options, wants an RFC-style brief, or needs evidence before implementation. Read-only; spikes and dependency adds are a separate, asked-for step. Hand off to fix-it / recon issue / issues create when ready to plan or track. argument-hint: "[question|library|API|approach...]" --- # Research It Replace vibes with **evidence**: what exists, what fits this repo, what to do next. ## Operating contract Shared by every DecisionNerd/dev-skills skill. Canonical copy: `handbook/concepts/14-operating-contract.md`. - **Define done first.** Before using tools, write the finish line in one or two lines: acceptance criteria (existing issue AC, BDD scenarios, tests, or contract; otherwise propose them and where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on unverified work. - **Requested scope sets the finish line.** A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a `Next:` line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work. - **Stop only for real blockers.** Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action. - **Ask well, once.** For a genuine question use the harness's structured question tool when it has one (Claude Code: `AskUserQuestion`; Codex: `request_user_input` when the current mode supports it; T3 Code: the `question` tool) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked. - **Fan out when work is parallel.** Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each result before consolidating. Use Claude Code's `Workflow` tool only when orchestrating many subagents truly needs it; it is expensive. T3 Code: its delegated subagents — with optional worktree isolation for independent verification — cover this without the `Workflow` tool. - **Pick the model tier per child; defer to routing config.** If the harness or user config already routes subagents, follow it and do not pass a model. Otherwise pick a tier per child: mechanical search or inventory → fast/cheap; implementation and evidence gathering → mid; planning, review, adversarial verification → top. Tier names differ per harness (Claude Code: `haiku` / `sonnet` / `opus` or `fable`; T3 Code: inherit by default or pick from its live provider/model catalog). Set the choice with the harness's spawn `model` param or agent frontmatter `model:` (per-harness details: `skills/agents/references/sub.md`). Where the harness cannot choose, children inherit or the harness picks; say which in the status note. - **Keep a checklist on long runs.** For more than about five steps or work that crosses skills, keep `TASKS.md` at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one. - **Close every run with three headings.** `Blocked on me` (the one genuine question or blocker, else "none"); `Changed` (files, commits, GitHub objects, deploys, else "nothing"); `Found` (evidence, verdict, and `Next: `). ## When to use - "What's the best way to…?", "research it", vendor/API comparison, spike before build - Ambiguous architecture choice before `recon issue` or `fix-it` - Need external docs or in-repo prior art surveyed first ## Workflow Done when: one recommendation tied to this repo's constraints, rejected options listed, unknowns named with what a spike would prove. 1. **Frame the question** - Decision to make, constraints (stack, latency, cost, compliance, timeline), success criteria. 2. **Search inward then outward** - In-repo: existing packages, patterns, ADRs, prior PRs/issues. - External: official docs (WebFetch), reputable references; note versions/dates. - Don't treat random blogs as authority over primary docs. 3. **Compare options** - 2–4 viable options max. Fan out one read-only subagent per option (mid tier) with a fixed criteria table as return shape: fit, complexity, ops burden, risk, lock-in. Mark every unconfirmed claim `unconfirmed` with its source location. - An adversarial reviewer subagent (top tier) attacks the leading recommendation before it is finalized. - Prefer **house defaults when unconstrained**: React + Next on Vercel for web; Pulumi ESC + OIDC for secrets; Langfuse for LLM obs/evals — unless the repo already standardized elsewhere. - Call out unknowns and what a spike would prove. 4. **Recommend** - One primary recommendation with rationale tied to *this* repo's constraints. - Explicit non-goals / rejected options with why. 5. **Next steps** - Next: `issues create` / `recon issue` / `fix-it` to plan or track; a time-boxed spike checklist when unknowns remain. - Spikes and dependency adds are a separate, asked-for step — express them as a `Next:` statement, not a question. ## Guardrails - Read-only unless the user asks to spike code or add a dep. - Cite sources (URLs/paths). Distinguish fact vs inference. - No secret keys in research notes. ## Output ```markdown **Question** - ... **Constraints** - ... **Options** | Option | Fit | Cost/complexity | Risk | Notes | | ... | **Recommendation** - Primary: ... - Why: ... - Rejected: ... **Open questions / spike** - ... ## Blocked on me none ## Changed nothing ## Found - ... - Next: issues create / recon issue / fix-it ``` ## Grounding This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook `sources.md`). Evidence before commitment; avoid jumping to complex systems before a simple one works (Gall's Law / Beck). Prefer house defaults only when the repo has no stronger local constraint (`handbook/concepts/11-quality-regimes.md` for generative tooling; `repos` for ESC). Handbook card: `handbook/practices/research-it.md`.