Research

Research

Always run this skill after /shape and before /write-a-prd. It auto-calibrates depth: sometimes it's a 2-minute version check that confirms your approach is still valid, sometimes it's a 30-minute deep dive into unfamiliar territory. The point is that it always runs — you don't get to skip it — because the most expensive research failures are the ones where you didn't know you needed to research.

This is also the first anti-anchoring checkpoint in the workflow. If the user or an earlier conversation introduced a date, budget, or confidence claim, clarify whether it is a target, an estimate, or a commitment before carrying it forward into the PRD.

> One question per turn. When confirming constraints, reviewing findings, or asking the user anything, ask one question at a time and wait for the answer before asking the next. Never present a batch of questions as a numbered or bulleted list. > > Prefer single-select. Use single-select multiple choice when the user is choosing one direction, one priority, or one next step. > > Use multi-select rarely. Reserve it for compatible sets — goals, constraints, non-goals, success criteria — that can all coexist. If prioritization matters, follow up asking which selected item is primary. > > Use the platform's question tool when available. In Claude Code, use AskUserQuestion; in Codex, request_user_input; in Gemini, ask_user. Otherwise, present numbered options in chat and wait for the user's reply before proceeding.

Invocation Position

This is a primary pipeline skill, not an optional extra. The default flow is /shape → /research → /write-a-prd.

Use /research whenever the work is headed toward shaping or implementation and you need to verify current versions, official docs, existing code patterns, and past solutions before making design commitments.

Do not skip this step just because the approach feels obvious. Do not use it as a replacement for /shape when the problem is still underdefined, and do not use it as a replacement for /execute once the work is already shaped and ready to implement.

Why This Is Mandatory

AI models are trained on internet-scale codebases where deprecated patterns outnumber current ones by orders of magnitude. The model will confidently generate middleware.ts for a Next.js 16 project where the file was renamed to proxy.ts. It will use getServerSideProps in an App Router project. It will suggest packages that don't exist. The only defense is to verify against reality before committing to an approach.

Execution Flow

Phase 0: Environment & Version Check (MANDATORY — never skip)

This phase takes 30-60 seconds and catches the most dangerous class of errors: stale API patterns from training data.

1. Read the dependency manifest. Extract installed versions of all major dependencies:

```bash # JavaScript/TypeScript projects cat package.json | jq '.dependencies, .devDependencies' 2>/dev/null

# Python projects cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null

# Rust projects cat Cargo.toml 2>/dev/null ```

1. Identify the key dependencies for this feature. Based on what /shape established, which dependencies will this feature touch? List them with their installed versions.

1. Check for breaking changes. For each key dependency, do a targeted web search:

`` "[dependency name] [installed version] breaking changes migration" "[dependency name] [installed version] vs [latest version] API changes" ``

Look specifically for:

• API renames (middleware.ts → proxy.ts)
• Removed or deprecated methods
• Changed function signatures (sync → async)
• Changed file conventions (pages/ → app/)
• Changed import paths
• Young features: features the feature-under-research depends on that the changelog or docs flag as "Added in X.Y" / experimental / beta / alpha, where the gap from X.Y to the installed version is small (rough heuristic: introduced within ~6 months of the installed version's release). Surface these as a 📦 YOUNG FEATURE flag listing the affected feature names — they need an upstream-issue-tracker audit in Phase 4 step 3 before the recommendation is finalized. Docs describe what is supposed to work and types describe what compiles; only the issue tracker describes what is currently broken in version X.Y against integration Z.

1. Check CLAUDE.md / AGENTS.md. Read any existing project context files for version constraints or conventions that override default patterns.

1. Flag mismatches. If any dependency has known breaking changes between the installed version and what the model's training data likely contains, flag them immediately:

`` ⚠ VERSION ALERT: Next.js 16.1 installed — middleware.ts was renamed to proxy.ts in v16. Do NOT use middleware.ts patterns. ⚠ VERSION ALERT: React 19 installed — forwardRef is no longer needed, ref is a regular prop. ⚠ VERSION ALERT: Drizzle ORM 0.35+ — schema definition API changed significantly from 0.28. ``

1. Spec-anchor check (intra-repo claims). Steps 1–5 verify external dependencies. Step 6 verifies internal ones — concrete repo identifiers carried in from /shape that the PRD will treat as ground truth. The same false-confidence failure mode applies: a model can name a file path, table, function, exported symbol, or test file that doesn't exist, and downstream skills will inherit the phantom anchor as a contract.

Enumerate the identifiers /shape referenced — file paths, schema/table names, function or type names, test files, named patterns ("the existing X loader," "the canonical Y format"). For each, confirm it resolves in the current repo:

```bash # File path or directory test -e || echo "MISSING: "

# Exported symbol (function, type, class, const) rg -n --type ts "export (function|const|class|interface|type) \b"

# Schema table or named structure rg -n "" drizzle/schema.ts # or equivalent for the project ```

Flag every identifier that doesn't resolve, and flag every vague-noun reference that resists grepping ("the chunks table" without a name, "the existing pipeline tests" without a path, "the same loader path the reranker uses" without a function). Vague nouns are the canonical site of spec-rot — they survive /execute Step 0's Consumes-verification gate (which only fires on named symbols) and only surface at /pre-merge. Resolve each by either pinning the exact identifier or rewriting the claim in terms that don't pretend an entity exists.

Format mismatches as spec alerts so they are visually distinct from version alerts:

`` ⚠ SPEC ALERT: PRD references "knowledge_chunks table" — no such table in drizzle/schema.ts. Closest match: knowledgeObjects (chunks generated in-memory by src/scripts/embed-knowledge.ts). ⚠ SPEC ALERT: PRD says "mirroring existing pipeline tests" — no test file exists at src/mastra/rag/*.test.ts. Pattern is invented, not extended. ``

Keep this within Phase 0's 30–60s budget — only check identifiers actually surfaced in /shape, not every name in the repo.

Phase 1: Auto-Calibrate Depth

Based on Phase 0 results, determine the research depth:

TARGETED (2-5 min) — Use when:

• Phase 0 found no version surprises
• The feature extends existing patterns already in the codebase
• No external APIs or unfamiliar libraries involved
• The approach is clear from the shape session

For TARGETED depth: write a short research document (20-50 lines) containing the version check results, any relevant past solutions from docs/solutions/, and a confirmation that the planned approach is valid for the installed versions. Skip the full template sections (Don't Hand-Roll, Options Evaluated, etc.). Move on to Phase 5.

STANDARD (10-20 min) — Use when:

• Integrating with a familiar external service using a new feature
• One dependency has a version mismatch that needs investigation
• A single technical decision needs evaluation (but not a wide-open choice)

DEEP (20-30 min) — Use when:

• Phase 0 found significant version mismatches
• The feature involves an external API or service not yet in the codebase
• Multiple valid technical approaches need evaluation
• An unfamiliar library with complex documentation is involved

Tell the user which depth was selected and why. If they disagree, adjust.

Phase 1.25: Library Callback Contracts

Only runs when the feature implements a library-provided callback surface. Triggers include: agent prepareStep/onStepFinish/before*/after* hooks, Express/Koa/Next middleware and proxy functions, AI SDK tool execute handlers, render props and higher-order components, lifecycle methods, interceptors, or any other shape where the library hands the application a callback to implement.

Phase 0 verifies APIs the feature calls. Most features stop there. When the feature also implements a callback the library defines, TypeScript's excess-property check does not run on returned values typed against local wrapper interfaces — any field the library's signature does not declare is silently discarded at runtime, even when the build passes. Pin the contract here, once, so /write-a-prd cannot codify a non-existent mechanism and /execute cannot wrap the return in a superset type.

For each callback the feature will implement:

1. Open the installed type definition. Grep node_modules//**/*.d.ts (or the equivalent for the language) for the callback's type name. Note the file path and line number.
2. Record the accepted return shape verbatim. Paste the return-type declaration — every field, optional marker, and union arm. Do not paraphrase.
3. Name the replace-vs-merge semantics. If the return includes a field that hands the library a collection (system messages, headers, tools, middleware stack), confirm in the library source whether the library replaces the existing collection with your return or merges into it. Replace semantics are the highest-risk class: the callback must reconstruct whatever it wants preserved.
4. Flag any wrapper-type plans. If the shape session imagined a mechanism (e.g. "inject via system override") that doesn't appear in the recorded shape, flag it as a design-time veto for the PRD. Do not downgrade to "we'll figure it out in /execute."

This step is gated — it only runs when a callback surface is in play — so Phase 0's 30–60s budget is preserved for features that only call libraries.

Phase 1.5: API-Shaped Work Check

After selecting depth, determine whether the feature needs focused API contract review.

Invoke /api-design-review only if at least one of these is true:

• a new external or partner-facing API is being introduced
• an existing request or response contract is changing
• OAuth, scopes, token model, or webhook verification is involved
• there is real uncertainty about paradigm selection

You may also invoke it for internal APIs with multiple independent consumers when a contract mistake would create broad cleanup cost.

Do not invoke it for ordinary implementation work that merely calls an API without shaping the contract.

If /api-design-review runs, incorporate its verdict into the research document rather than duplicating a second full API review.

Phase 2: Establish Constraints

State the constraints from the shape session. These bound the research and prevent scope drift. Present each constraint one at a time, ask the user to confirm or correct it, then move to the next:

1. What is the feature trying to accomplish? (1-2 sentences from shape)
2. What are the hard constraints? (scale, budget, self-hosted vs managed, latency, auth model, etc.)
3. What decisions are already locked? (framework, language, deployment target, etc.)
4. What version constraints did Phase 0 surface? (list any flags)
5. If timing language exists, what is currently a target, what is currently an estimate, and what is explicitly not yet a commitment?

Do not present these as a batch. State one constraint, get confirmation, then proceed to the next.

Phase 3: Consult Past Solutions

Search docs/solutions/ for relevant past solutions:

grep -rl "relevant-keyword" docs/solutions/ 2>/dev/null

If relevant solutions exist, read them and incorporate their lessons. Note which past pitfalls or patterns apply. This is the compounding benefit — past work makes future research faster and more accurate.

Scope check before transfer. When a loaded solution doesn't state explicit scope or preconditions (the Rule Scope section added by /compound), or when its stated scope doesn't match the current work's structural shape, re-derive the recommendation from first principles rather than transferring it. A rule correct for a 2-step agent loop with a terminal forced tool can invert for a 3-step loop where the same tool is non-terminal — keyword match is not shape match. Verify the shape, don't skip the check.

Staleness check: When reading a docs/solutions/ file, check its volatility YAML field and date. If volatile and older than 90 days, or if the Shelf Life condition appears to have been met, note it as potentially stale before incorporating its lessons. Flag stale docs to the user — they should be updated or deleted.

Phase 4: Research

Research the codebase and relevant technologies. Use sub-agents in parallel when investigating multiple options.

1. Explore relevant existing code — What patterns exist? What integration points are available? What constraints does the current architecture impose?
2. Fetch current documentation — If Context7 MCP is available, use resolve_library and get_library_docs for the specific installed version. If not, use web search targeting official docs for the installed version — never the "latest" version unless it matches what's installed. Also check for llms.txt at the library's documentation site.
3. Verify every API reference — Do NOT trust training data for any framework API call. Every API method, import path, file convention, or function signature in your research output must trace back to either: (a) the installed version's official documentation, (b) a verified web search result, or (c) existing working code in the current codebase. When an API call goes through an SDK that wraps a remote provider (LLM SDKs over model APIs, cloud SDKs over service APIs, payment/auth SDKs over upstream services), the citation under (a) must include the provider's contract docs in addition to the SDK's types — the SDK's type signature is the upper bound of what compiles; the provider's contract is the lower bound of what executes. Concretely: when handing a JSON Schema, Zod schema, tool definition, or structured-output spec across an SDK→provider boundary, cite both the SDK's type for the field (e.g. Output.object({ schema })) and the provider's schema-subset documentation (e.g. Gemini response_schema, Anthropic tool.input_schema, OpenAI Structured Outputs subset). If you cannot verify an API reference, mark it explicitly: "⚠ UNVERIFIED — could not confirm this API exists in [version]."

Citation required in the written output. For each verified claim, record one of the following in the research document itself — not only in your reasoning: an official docs URL at the verified version, a file path and line number from node_modules//**/*.d.ts, or a grep result showing the behavior in the project's codebase. "I confirmed this works" without a traceable citation is not verification. The citation is what makes the research auditable by /write-a-prd and /execute. If you cannot produce a citation, mark the claim as Uncertain and elevate it to Phase 2 as a first-priority constraint.

Calibrate filed-issue evidence. The upstream issue tracker is a first-class source for what is currently broken — not what a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chrislacey89
• Source: chrislacey89/skills
• License: MIT
• Homepage: https://skills.sh/chrislacey89/skills

Install and usage instructions live in the source repository linked above.