| name | research-context |
| description | Use when a decision needs current external/web info (library best-practices, version behavior, migration guidance) rather than local sources — runs grounded web research and returns a cited brief. |
| type | skill |
| license | MIT |
| compatibility | ["claude-code"] |
| trigger | research-needed|current-best-practice|version-sensitive-decision|external-info-grounding |
| skip_when | behavior-verifiable-from-local-repo|well-understood-stable-api|no-external-uncertainty |
| triggers | ["best-practice","best-practices","latest-version","upgrade-guide","migration-guide"] |
| user-invocable | false |
Research Context
Overview
source-driven-development answers "does this known API behave the way I think?" by checking authoritative docs for one call. research-context answers the broader, forward-looking question: "given what this repo already does, what is the current best way to do X?" — pulling fresh external information (release notes, current best-practices, migration paths, security advisories) and grounding it against named files in this repo so the answer fits the codebase, not a generic tutorial.
It is the MTK analog of Taskmaster's research mode: research is a first-class workflow primitive, not an ad-hoc web search. Its output is a small, cited brief that downstream skills consume — spec-driven-development (version-sensitive ambiguity gate, step 6) and implement (Phase 3, version-sensitive choices) — so spec and implementation decisions ride on current information rather than training-cutoff memory.
This skill does not edit code. It produces a brief; another skill acts on it.
Tool discipline (phase-locked): research is a read + web-fetch phase — use Read/Grep/Glob and the web tools only. Do not Edit/Write source or test code; the only artifact it may write is its own brief. (It is not locked to the read-only toolset because it legitimately needs WebSearch/WebFetch, which that toolset excludes.)
Model tier: runs on sonnet (synthesis of external sources into a cited brief) per .claude/references/model-routing.md.
When To Use
- A spec or plan hinges on a version-sensitive choice (which API/pattern is current in the installed package version, not the one from memory).
- Choosing between competing libraries/approaches where the landscape moved recently.
- A dependency upgrade or framework migration where the migration path matters.
- A security-sensitive decision where current advisories or deprecations could change the answer.
- The engineer literally asks to "research X" before building.
When NOT To Use
- The behavior is verifiable from local repo patterns already in use → use
source-driven-development (cheaper, no web).
- A single known-API contract question →
source-driven-development.
- Stable, well-understood APIs with no version sensitivity → just implement.
- The question is about this codebase's internals → read the code; this skill is for external information.
Workflow
Step 1 — Frame the question against the repo (grounding is mandatory)
Before any web call, anchor the research in concrete project context. Identify and name the files that constrain the answer:
- The active tech stack (read
.claude/tech-stack) and the relevant tech-stack-<stack>/SKILL.md.
- The installed version of the library in question — read it from the lockfile / project file (
*.csproj, Directory.Packages.props, requirements.txt, pyproject.toml, package.json). A research answer for the wrong version is worse than no answer.
- 1–3 existing files that show how the repo uses the relevant area today.
Write the framed question as: "For <stack> using <library>@<installed-version>, given that this repo currently does <X in file:line>, what is the current recommended way to <goal>?"
If you cannot name the installed version or a grounding file, say so in the brief — an ungrounded brief is explicitly marked as such.
Step 2 — Choose research depth
| Signal | Path |
|---|
One focused question, 1–2 likely authoritative sources (e.g. "is X deprecated in v8?") | Light path: WebSearch + WebFetch directly (2–4 fetches), or context7 MCP for library docs if available. |
| Multi-angle, contested, or high-stakes (architecture choice, security posture, "which of these 3 approaches") | Deep path: delegate to the built-in /deep-research workflow via the Skill tool, passing the framed question from Step 1. It fans out, cross-checks, votes per claim, and returns a cited report — do not re-implement that loop by hand. |
Prefer the light path. Escalate to /deep-research only when the question genuinely has multiple competing answers or the cost of being wrong is high (security, data integrity, a hard-to-reverse migration).
Step 3 — Ground findings against the named files
For each finding, classify it the same way source-driven-development does, and make the classification visible:
- verified-from-source — backed by a fetched authoritative source (link it).
- applies-to-this-repo — confirmed compatible with the installed version and existing patterns named in Step 1.
- conflicts-with-repo — current best-practice diverges from what the repo does today (flag explicitly; this is a decision for the spec/plan, not a silent override).
- still-uncertain — could not confirm against an authoritative source or against the installed version.
Step 4 — Emit the brief
Write a compact, cited brief (Markdown). Keep it short — it is consumed by another skill, not read for pleasure:
## Research brief: <framed question>
**Stack / version:** <stack> · <library>@<installed-version> (from <file>)
**Grounding files:** <file:line>, <file:line>
### Recommendation
<1–3 sentences: the current recommended approach for THIS version/repo>
### Findings
- [CITED:<url>] <claim> — confirmed against an external source
- [VERIFIED:<file:line>] <claim> — confirmed against this repo's code/config
- [ASSUMED] <claim> — could not confirm; stated as an assumption, NOT a fact
### Open decisions for the spec/plan
- <anything that needs an engineer or AskUserQuestion call downstream>
### Sources
- <url> — <one-line what it established>
Provenance tags are mandatory on every claim. Each finding carries exactly
one provenance tag so downstream skills can tell fact from guess:
[CITED:<url>] — backed by a named external source.[VERIFIED:<file:line>] — confirmed against this repo (installed version,
existing pattern, config value).[ASSUMED] — not confirmed. This is the load-bearing one: an [ASSUMED]
claim that reaches a spec becomes an open decision that blocks
MTK_AUTO_PROCEED at the implement Phase 2.5 gate (a human must confirm
it). Never launder an [ASSUMED] claim into a bare assertion — if you could
not confirm it, tag it, so the gate can catch it.
If invoked standalone (engineer said "research X"), present the brief and stop — do not start implementing. If invoked by spec-driven-development or implement, return the brief to that skill so its decisions and ambiguity gate consume it.
Step 5 — Persist when part of a workflow
If a workflow artifact is active ($MTK_WF_UUID set), record the brief so it survives compaction:
scripts/workflow-artifact.sh event "$MTK_WF_UUID" research_brief --data '{"question":"...","recommendation":"...","conflicts":<n>}'
Rules
- Ground before you search. No web call until the installed version and at least one repo grounding file are named (or their absence is recorded).
- Cite or it didn't happen. Every
verified-from-source finding carries a fetched URL. Memory is not a source.
- Version-match. A finding for a different major/minor version than the one installed is
still-uncertain until confirmed for the installed version.
- Surface conflicts, never resolve them silently. If current best-practice contradicts the repo, that is an open decision for the spec/plan — not something this skill changes.
- Don't implement. This skill produces a brief. Acting on it is another skill's job.
- Escalate deep, not wide. Use
/deep-research for genuinely multi-angle questions; don't hand-roll a fan-out.
Common Rationalizations
See .claude/skills/context-engineering/SKILL.md for the shared table. Research-context-specific traps:
| Rationalization | Reality |
|---|
| "I already know the best practice for this library" | Your memory has a training cutoff; the library shipped versions since. If the decision is version-sensitive, verify it for the installed version. |
| "I'll research the general approach, version doesn't matter" | Version is the whole point — a recommendation for v7 can be an anti-pattern in v9. Name the installed version first. |
| "Web result says X, so I'll just code X" | A blog from two years ago about a different version is not grounding. Classify the finding and check it against the installed version + repo patterns. |
| "Let me just implement while I research" | This skill produces a brief and stops. Implementing mid-research means acting on unverified findings. |
| "The repo does it differently, I'll quietly switch to the modern way" | A conflict between repo and current best-practice is a decision for the spec/plan, surfaced explicitly — not a silent rewrite. |
| "One quick web search is enough for this architecture call" | High-stakes, multi-answer questions go through /deep-research so claims get cross-checked and voted, not taken from a single page. |
Red Flags
- A brief with
verified-from-source findings that have no URLs.
- Findings stated without naming the installed library version.
- Research that never names a single file from this repo (ungrounded — generic tutorial output).
- The skill editing source files.
- A multi-angle architecture decision answered from a single web page instead of
/deep-research.
- Conflicts between repo and best-practice silently resolved instead of surfaced.
Verification
