---

name: research description: > Research current practice with Context7, Firecrawl, and official docs before a non-trivial change: gap analysis and a file-mapped plan, no implementation. Use when "look up current docs" or before anything unfamiliar. license: MIT effort: high

research — Production research protocol

Degree of freedom: MIXED. Repo-first inventory and official-docs order [LOW freedom — run exactly]. Which sources to trust and which pattern to recommend [HIGH freedom].

Understand the current repo first. Then fetch version-matched official docs. Then map findings back to specific files. Do not implement until the user asks or approves. Recognizing a library, tool, or product name is not knowing its current state. Search the name as written and fetch the installed version's docs even when you think you already know the answer — that is the whole point of this skill.

This skill vs neighbors

Skill	Owns
research (this)	Current-year, version-matched investigation + gap analysis + plan
plan-*	Audit → approved burndown (no implementation)
docs-adr	Decision memory after a choice is made
workflow-onboard	First-contact repo orientation, not industry research
complete-everything	Execute an already-approved plan

How to reason

1. Observe — installed versions, current files, existing pattern
2. Interpret — what is actually missing vs what just looks old
3. Classify — keep / replace / add / reject (deprecated, CVE, untyped)
4. Decide — one recommended approach mapped to concrete files

Worked example

Observe: consumer asked whether npx skills add overwrites slash commands; pack ships both commands/*.md and skills/*/. Interpret: two installers, two --all meanings; Cursor now slash-invokes skills so same-name pairs look duplicated. Classify: docs lie (skills add claimed to install commands); npm installer merge-overwrites correctly. Decide: keep npm installer as the full-pack path; add --verify; promote this protocol from command-only to a skill.

Self-critique

Before delivering the plan, fail the run if any of these are true:

• Repo files were not read before the first external search
• Official docs for the installed version were skipped when available
• A recommendation has no source, or only one weak blog post
• The plan is not mapped to concrete repo paths
• Implementation started without an explicit user ask

---

Step 1: Understand the codebase context — before any external search

Before any external research, understand what you're working with.

1a. Discover Tech Stack

Read the dependency manifest to get exact library names and versions:

package.json          (Node/JS/TS)
requirements.txt      (Python)
pyproject.toml        (Python)
Cargo.toml            (Rust)
go.mod                (Go)
build.gradle          (Java/Kotlin)
Gemfile               (Ruby)

Extract: framework, major libraries, their exact versions.

1b. Read the Existing Implementation

Read the specific file(s) related to the topic being researched, in full — conventions, limitations, and TODOs live outside the obvious lines. Understand:

• What pattern is currently used?
• What dependencies does it rely on?
• What are the known limitations or TODOs?
• What conventions does the project follow?

1c. Formulate Research Questions

Write out explicitly:

Current state: [what the project does now]
Gap/goal: [what needs to improve or be added]
Specific questions:
  1. [question about best practice]
  2. [question about alternative approach]
  3. [question about edge cases]

---

Step 2: Context7 — Official Documentation

Fetch current docs for the libraries involved. Use the Context7 MCP (if available).

Resolve Library ID

context7:resolve-library-id
{
  "libraryName": "<library-name>",
  "query": "<your specific question>"
}

Fetch Documentation

Pick the best match from the resolution results, then:

context7:query-docs
{
  "libraryId": "<selected-id>",
  "query": "<your specific question>"
}

Run Context7 for each major library involved. Prefer version-specific IDs when available.

If Context7 is unavailable, skip to Step 3 and use Firecrawl to search official documentation sites directly.

---

Step 3: Firecrawl — Three-Phase Deep Research

Use the firecrawl MCP server. The research happens in three phases: broad search, deep scrape, then discovery.

Phase 1: Broad Search (find what's out there)

Search without scraping first — get URLs and snippets to evaluate:

firecrawl:firecrawl_search
{
  "query": "[library] [topic] best practices [current year]",
  "limit": 5,
  "sources": [{ "type": "web" }]
}

Run 2-3 search queries with different angles:

Angle	Query Pattern
Best practices	[tech] [topic] best practices [current year]
Implementation guide	[tech] [topic] production implementation guide
Common mistakes	[tech] [topic] common mistakes pitfalls avoid
Migration/upgrade	[tech] [topic] migration guide from [old version]
Security	[tech] [topic] security OWASP [current year]
Performance	[tech] [topic] performance optimization production

Use search operators for precision:

• site: to target specific docs sites (e.g., site:react.dev, site:nextjs.org)
• "" for exact phrases
• - to exclude irrelevant results

Phase 2: Deep Scrape (read the best sources thoroughly)

From Phase 1 results, pick the 2-3 most authoritative URLs (official docs, maintainer blogs, engineering blogs). Scrape each for full content:

firecrawl:firecrawl_scrape
{
  "url": "<authoritative-url>",
  "formats": ["markdown"],
  "onlyMainContent": true
}

For extracting specific data points (config options, API parameters, migration steps):

firecrawl:firecrawl_scrape
{
  "url": "<docs-url>",
  "formats": ["json"],
  "jsonOptions": {
    "prompt": "Extract the recommended configuration options and their default values",
    "schema": {
      "type": "object",
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "recommended": { "type": "string" },
              "description": { "type": "string" }
            }
          }
        }
      }
    }
  }
}

If a documentation site is large and you're not sure which page has the answer, use firecrawl_map first to discover the right page:

firecrawl:firecrawl_map
{
  "url": "https://docs.example.com",
  "search": "[your topic]",
  "limit": 20
}

Then scrape the specific page(s) found.

Phase 3: Discovery (find reference implementations)

Search for real-world codebases that solved the same problem:

firecrawl:firecrawl_search
{
  "query": "[tech] [topic] example implementation github",
  "limit": 5,
  "sources": [{ "type": "web" }]
}

Also try:

Discovery Query	Purpose
[tech] [topic] open source example	Find real implementations
[tech] [topic] starter template boilerplate	Find scaffolded patterns
[tech] [topic] "how we" OR "how I" production	Find experience reports
site:github.com [tech] [topic] in:readme	Find repos directly

Scrape the README or relevant docs of promising repos to extract their architectural decisions.

---

Step 4: Gap Analysis (the core of research-driven enhancement)

Compare what the project currently does against what research found. Produce a structured gap analysis:

## Gap Analysis: [Topic]

### What the project does correctly
- [pattern 1]: aligns with [source] recommendation
- [pattern 2]: follows current best practice

### What the project is missing
- [gap 1]: [source] recommends X, project does Y or nothing
- [gap 2]: [source] warns against current pattern, suggests Z

### Anti-patterns detected
- [anti-pattern 1]: project uses [old pattern], [source] recommends [new pattern] because [reason]

### New capabilities available
- [capability 1]: [library] now supports [feature] as of v[X], not yet adopted
- [capability 2]: [new approach] reduces complexity, project uses legacy pattern

---

Step 5: Fallback — WebSearch + WebFetch

When Firecrawl MCP is unavailable, use built-in tools with the same three-phase approach:

Phase 1: Broad Search

WebSearch(search_term: "[tech] [topic] best practices [current year]")

Phase 2: Deep Read

WebFetch(url: "<authoritative-url-from-search>")

Phase 3: Discovery

WebSearch(search_term: "[tech] [topic] github example implementation")

---

Step 5b: Grounding contract [LOW freedom — run exactly]

Every fact that reaches the plan carries its source. This is what keeps the plan from drifting into confident filler.

• Cite or abstain. A claim gets a URL (or a repo file:line) and the date you read it. A claim with no source is written as [unverified] or dropped.
• Date the query. Search with the current year in the query and prefer pages dated this year or last. Record the publication date next to the source.
• Pin the version. Library facts name the version they apply to (FlashList v2, Capacitor 8.3.2+), never "the latest".
• Quote the primary source once. Vendor docs, changelogs, RFCs, and standards bodies outrank blog posts. When only a blog says it, say so.
• Separate observation from inference. "The docs say X" and "so the repo should do Y" are two sentences.
• Numbers are measured, not remembered. Any figure (chars, ms, %) comes from a command you ran or a page you read, and the plan names which.

The same contract applies to prose you ship: docs-writer's references/plain-language-ste.md has the writing side (plain language, no AI tells) and a prose-lint recipe.

Step 6: Synthesize and Decide

Trust Hierarchy (when sources conflict)

1. Official documentation (highest trust)
2. Core maintainer posts / RFCs / changelogs
3. Engineering blogs from major companies (Vercel, AWS, Google, Meta)
4. GitHub discussions on official repos
5. Community articles with high engagement (current year, verified working)

Conflict Resolution

When two authoritative sources recommend different approaches:

1. Check which source matches the project's installed version
2. Check which approach aligns with the project's existing patterns
3. Check which approach has fewer trade-offs for the project's scale
4. If still tied, prefer the simpler approach

Validation Gates

Gate	Check
Fresh	Published current year or previous year, matches installed version
Secure	No known CVEs, follows OWASP guidelines
Typed	Full TypeScript support, no any escape hatches
Tested	Can be unit/integration tested, doesn't break existing tests
Compatible	Works with the project's other dependencies and patterns

Reject a pattern if: it uses a deprecated API, has known vulnerabilities, skips error handling, requires a major refactor with unclear benefit, or conflicts with the project's architecture.

---

Step 7: Plan Complex Implementations

Plan multi-file architectural migrations directly in the plan: ordered files, intermediate states, side effects. Thinking is native — the Sequential Thinking MCP is not shipped (ADR-0009) and adds nothing here.

Do not add Playwright MCP for research or browser checks — use headed playwright-cli per protocol-browser-anti-stall. Firecrawl stays authenticated; do not switch to the keyless tool subset just to save tokens.

---

Step 8: Apply to Codebase

Map every research finding to specific, actionable code changes. Do not implement in this skill.

## Implementation Plan

### Changes (ordered by priority)

1. **[file path]** — [what to change and why]
   - Before: [current pattern]
   - After: [recommended pattern]
   - Risk: [low/medium/high] — [explanation]

2. **[file path]** — [what to change and why]
   ...

### New dependencies (if any)
- [package@version] — [why needed]

### Breaking changes
- [description of what breaks and how to migrate]

### Edge cases to handle
- [edge case 1]
- [edge case 2]

### Verification
- [how to verify the change works]

---

Output Template

After completing research, produce this summary:

## Research: [Topic]

### Context
- Tech stack: [framework, libraries, versions]
- Current implementation: [brief description]
- Research goal: [what we're trying to learn/improve]

### Findings
[Key patterns and recommendations from research]

### Recommended Approach
[Pattern name] — [one-line why this is best for this project]

### Gap Analysis
- Missing: [what the project should add]
- Replace: [what the project should change]
- Keep: [what the project already does well]

### Implementation Plan
[Ordered list of file changes with before/after]

### Gotchas
- [Edge case or risk 1]
- [Edge case or risk 2]

### Sources
- [URL] — [what it provided]
- [URL] — [what it provided]

---

Pre-Implementation Checklist

• Codebase context understood (tech stack, current patterns, specific files read)
• Context7 docs fetched (or skipped if unavailable)
• Firecrawl broad search completed (2-3 queries)
• Firecrawl deep scrape completed (2-3 best URLs)
• Discovery search completed (reference implementations found)
• Gap analysis produced (current vs recommended)
• Sources cross-referenced (3+ sources agree)
• Validation gates passed (fresh, secure, typed, tested, compatible)
• Implementation plan maps findings to specific files
• Edge cases identified