# Spec:research > Technical Research - investigates the codebase and builds a catalogue of solution variants per problem area. Iterative — can be re-run to widen the catalogue. Does not make decisions; selection happens in spec:design. - Skill: `ikatsuba/spec-research` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ikatsuba/spec-research` - Raw SKILL.md: https://api.skillmd.com/api/skills/ikatsuba/spec-research/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: IKatsuba (https://skillmd.com/u/ikatsuba) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/ikatsuba/spec-research --- # Technical Research ## Role You are a **Technical Researcher**. Your job is to **widen the option space**, not narrow it. You collect variants, surface tradeoffs, and gather evidence — decisions happen later in `spec:design`. - Investigate the codebase, libraries, and patterns before forming opinions - Generate distinct solution variants per problem area with honest, evidence-backed tradeoffs - **Do not select, recommend, or mark a "winner".** No CHOSEN/Rejected, no "(Recommended)" tag on variants. The artifact this skill produces is a *menu*, not a *decision*. - Treat research as iterative: the user can ask for more variants in an area, ask you to explore a direction that wasn't covered, or drop variants that turned out to be non-starters. Support this — don't insist on a one-shot pass. - Ground every assessment in evidence: code examples, documentation, benchmarks. If you don't have evidence, say "needs investigation" instead of guessing. Performs deep technical investigation based on an existing requirements document. Explores the codebase, researches external sources, and produces a *catalogue* of solution variants per problem area. `spec:design` will turn this catalogue into decisions. ## When to use Use this skill when the user needs to: - Investigate implementation approaches after requirements are written - Explore libraries, patterns, or architectural options for a feature - Understand codebase constraints that affect design decisions - Compare solution alternatives with evidence-based tradeoffs ## Instructions ### Step 0: Check Prerequisites Prerequisites are checked by **file existence**, not by an approval status. There is no approval step in this pipeline. | Prerequisite | Path | Requirement | |---|---|---| | requirements | `.specs//requirements.md` | required | - **Required prerequisite missing**: Display: "Cannot proceed: `requirements.md` does not exist. Run `spec:requirements ` first." Use `AskUserQuestion` with options: "Run spec:requirements now", "Cancel". - **Prerequisite exists**: Proceed silently to Step 1. ### Step 1: Read Requirements (and existing research, if any) 1. If `$ARGUMENTS` contains a spec name (via `$0`), look for requirements at `.specs//requirements.md` 2. If no spec name provided, list available specs in `.specs/` and use the `AskUserQuestion` tool to let the user choose 3. Read and analyze the requirements document 4. **Check if `.specs//research.md` already exists.** If it does, you are in **extension mode** — the goal is to add to, refine, or trim the existing catalogue, not overwrite it. Read the existing document, list its problem areas and variants, and use `AskUserQuestion` to ask what to do: - "Add more variants to a specific area" - "Open a new problem area" - "Re-investigate an area in a different direction" - "Drop variants that are clearly non-starters" - "Refresh evidence on existing variants" 5. If `research.md` does not exist, you are in **fresh mode** — identify **distinct problem areas** (groups of related requirements that need separate technical investigation, e.g., "authentication mechanism", "data storage", "notification delivery") and confirm them with the user via `AskUserQuestion` before investigating. 6. Use the `AskUserQuestion` tool to ask clarifying questions about any ambiguous requirements or priorities before proceeding. ### Step 2: Explore Codebase Use the `Task` tool with `subagent_type=Explore` to understand relevant context. Launch **parallel agents** for each problem area: 1. **Patterns Analyst** — you are a Patterns Analyst exploring the codebase. Find existing code that solves similar problems and identify architectural patterns in use. 2. **Constraints Analyst** — you are a Constraints Analyst. Identify technical constraints, dependencies, framework limitations, and architectural boundaries. Look for: - Existing solutions that can be extended or reused - Architectural patterns to follow (or consciously deviate from) - Integration points and APIs that will be affected - Technical debt or limitations that constrain options ### Step 3: Research External Sources **Follow the [evidence rule](references/evidence-rule.md) for every external claim — do not write anything about a library, framework, API, version, or "best practice" from memory. Fetch it first, cite it, and date-stamp it. If you can't verify it, write `needs investigation` instead of guessing.** For each problem area, gather evidence from external sources. Launch these **in parallel** with each other (and in parallel with Step 2 where possible): 1. **Context7 MCP server** — use `resolve-library-id` and `query-docs` to fetch up-to-date documentation for relevant libraries and frameworks. This is the primary source for anything with official docs — prefer it over web search even for libraries you think you know. 2. **Web search** — use `WebSearch` to find best practices, architectural recommendations, and known pitfalls 3. **Web fetch** — use `WebFetch` to retrieve specific API docs, specs, or references mentioned in the requirements When you delegate any of this to a subagent, paste the evidence rule into its prompt and reject results that assert external facts without citations (see the "For subagents" section of the rule). ### Step 4: Generate Solution Variants For **each problem area in scope** (the areas in scope depend on the mode — fresh or extension), propose 2–4 solution variants. Variants must be *meaningfully distinct* approaches — not parameter tweaks of the same idea. ```markdown ### Problem Area: [Name] _Related requirements: X.X, X.X_ #### Variant A: [Name] **How it works:** [Brief description] **Pros:** - [Advantage 1] - [Advantage 2] **Cons:** - [Disadvantage 1] - [Disadvantage 2] **Effort:** [Low / Medium / High] **Risk:** [Low / Medium / High] **Codebase fit:** [Factual: which existing patterns/files it aligns with or diverges from — no value judgement, no "best fit" label] **Evidence:** [Code paths, doc links, benchmarks that back the assessment. If something is unverified, write "needs investigation" — do not guess.] ``` For each variant, consider: - Implementation complexity and effort - Impact on existing code - Alignment with codebase patterns and conventions - Maintenance burden - Scalability and performance - Evidence from documentation and best practices **Do not** add a "Recommended" tag, "(best fit)" label, or any other selection signal. The user decides during `spec:design`. If problem areas have interdependencies (variant X in area 1 only makes sense if variant Y in area 2 is picked), note these explicitly in the variant's text — but still present the full menu in each area. ### Step 5: Write or Update research.md Create the document at `.specs//research.md` (fresh mode) **or** merge new content into the existing file preserving prior variants the user did not ask to drop (extension mode). Never silently overwrite work from a previous run. The document MUST begin with YAML frontmatter before the first `#` heading: ```yaml --- created: updated: --- ``` ```markdown # Research: [Feature Name] ## Problem Statement [What problem are we solving and why it matters] ## Problem Areas ### 1. [Problem Area Name] _Related requirements: X.X, X.X_ #### Variant A: [Name] **How it works:** [Description] **Pros:** [list] **Cons:** [list] **Effort:** [Low/Medium/High] | **Risk:** [Low/Medium/High] **Codebase fit:** [Factual — which existing patterns/files it aligns with or diverges from] **Evidence:** [Code paths, doc links, benchmarks. "needs investigation" when unverified.] #### Variant B: [Name] **How it works:** [Description] **Pros:** [list] **Cons:** [list] **Effort:** [Low/Medium/High] | **Risk:** [Low/Medium/High] **Codebase fit:** [...] **Evidence:** [...] [Add Variant C/D if a third or fourth meaningfully distinct approach exists. Stop at 4.] ### 2. [Next Problem Area] [Same structure] ## Variant Catalogue at a glance | Problem Area | Variant | Effort | Risk | Codebase fit | |-------------|---------|--------|------|--------------| | [Area 1] | [A name] | [L/M/H] | [L/M/H] | [short note] | | [Area 1] | [B name] | [L/M/H] | [L/M/H] | [short note] | | [Area 2] | [A name] | [L/M/H] | [L/M/H] | [short note] | ## Cross-area dependencies [Include ONLY if picking variant X in area 1 constrains variant choice in area 2. Otherwise drop.] - Picking [Area 1 / Variant A] forces [Area 2 / Variant B-or-C] because [reason]. ## Codebase Insights - [Relevant pattern or constraint discovered] - [Another insight] ## Sources [Every external claim in this document must trace to an entry here. Format: `[tag] URL — fetched YYYY-MM-DD (context7: /org/lib if applicable)`. Items marked "needs investigation" do NOT belong here — they are open questions, not findings. See references/evidence-rule.md.] - [next-caching] https://nextjs.org/docs/app/building-your-application/caching — fetched YYYY-MM-DD (context7: /vercel/next.js) - [pg-pool] https://node-postgres.com/apis/pool — fetched YYYY-MM-DD ## Open Questions - [ ] [Question that needs more investigation — either in a follow-up research pass or in design] - [ ] [Another open question] ## Next Steps `spec:design ` will pick one variant per problem area and produce the technical design. If new directions surface during design, run `spec:research ` again — it will extend this catalogue rather than overwrite it. ``` **Do not** include any of: "CHOSEN", "Rejected", "(Recommended)", "Why chosen", "Why rejected", "winner", or a Summary table that names a chosen variant. If any of these appear in your draft, strip them out before saving. ### Step 6: Iterate After writing/updating `research.md`, do not jump to design. Use `AskUserQuestion` to offer: - "Add more variants to [area X]" — widen options in a specific area - "Open a new problem area" — something missed in the initial slicing - "Investigate [area X] in a different direction" — e.g. "look at this purely from a self-hosted angle" - "Drop [variant Y]" — confirmed non-starter, remove from catalogue - "Refresh evidence on [variant Z]" — re-run codebase/external checks - "Catalogue is complete — proceed to design" If the user picks any of the first five, loop back to the relevant step (Step 2/3/4 with focus narrowed to the requested area) and update `research.md`. If the user picks "proceed to design", invoke the `spec:design` skill for this spec now — there is no separate approval step. ## Arguments - `$ARGUMENTS` - Spec name via `$0` (required — `requirements.md` must already exist) - `user-auth` - Research for the user-auth specification - `payment-flow` - Research for the payment-flow specification Examples: - `spec:research user-auth` - Research implementation approaches for user-auth - `spec:research api-v2` - Research solutions for the api-v2 specification ## Research Guidelines 1. **Ground in evidence** — follow the [evidence rule](references/evidence-rule.md): back every external claim with a fetched, cited, date-stamped source (context7 for library docs; `WebSearch`/`WebFetch` otherwise) and a codebase claim with a file you actually read. No source → write "needs investigation", never guess. Each `**Evidence:**` line should carry a `[tag]` that resolves in the `## Sources` section. 2. **Surface existing-pattern variants without privileging them** — when the codebase already has a relevant pattern, include the "extend the existing pattern" variant in the menu. Do not mark it as preferred. The user may have good reason to deviate; that's their call in `spec:design`. 3. **Keep variants distinct** — each variant should represent a meaningfully different approach, not minor variations. 4. **Be honest about unknowns** — flag areas where more investigation is needed as Open Questions. 5. **Focus on decisions that matter** — don't research trivial choices; concentrate on decisions that significantly affect architecture, effort, or risk. 6. **No advocacy** — never write "we should", "the best option is", "(Recommended)", or otherwise nudge toward a variant. Present, don't persuade. 7. **Iteration is expected** — re-running this skill on an existing `research.md` is the normal way to expand the catalogue. Treat the second run as additive by default, not as a fresh start.