---
name: skill-taskmaster-doc-research
description: Use after task-master expand --all and skill-taskmaster-research-advanced
(Fase 2). For each specified task, searches official documentation and creates /doc files
in repo root, then updates tasks.json details with references. Two modes: MODE A (default)
uses Ref MCP -> Context7 -> Exa -> GitHub chain; MODE B (ref-codebase) uses Ref MCP
codebase search on pre-indexed repos. Gracefully degrades to built-in web search if no
MCPs are available — always executable. Triggers: "research docs for task", "fetch docs
for task", "doc research", "create doc files for task", "use ref codebase", "search my
repos for task", "ref indexed search".
---

# Skill: Taskmaster Doc Research

For each specified task: search docs, create /doc files, update tasks.json with references.
Bridges the gap between task planning and implementation by pre-fetching all needed documentation.

**Always executable** — degrades gracefully from MCP tools to built-in web search.

Two modes:
- **Mode A** (default): searches official docs online via Ref → Context7 → Exa → GitHub chain
- **Mode B** (ref-codebase): searches your pre-indexed repos on Ref.tools using `ref_search_codebase`

---

## Position in Fase 3 (Step 1)

task-master parse-prd --input .taskmaster/docs/prd.md
task-master expand --all
→ skill-taskmaster-research-advanced (Perplexity research — Fase 2, updates task descriptions)
→ skill-taskmaster-doc-research ← YOU ARE HERE (Fase 3, Step 1)
MODE A: online docs chain | MODE B: Ref codebase indexed search
Creates doc/ files + updates tasks.json details with doc references
Also: adversarial PRD check — verifies tasks/subtasks, deepens implementation
patterns, code exploration + selection + readapt for the project
→ USER reviews tasks.json
→ Fase 3: skill-parallel-wave-report
→ Fase 3: skill-github-project-issue-manager

text

---

## Step -1: Tool Discovery (ALWAYS run first)

Before doing anything else, check which tools are available in this session.

### Check MCP availability

Verify which of these tools are available (check tool list):
MCP tools:
- ref_search_documentation (Ref MCP — docs search)
- ref_search_codebase (Ref MCP — codebase search)
- ref_read_url (Ref MCP — read full page)
- context7_resolve-library-id (Context7 MCP)
- context7_get-library-docs (Context7 MCP)
- exa_search (Exa MCP)
- exa_get_contents (Exa MCP)
- searchGitHub (Grep MCP)
- perplexity_search (Perplexity MCP)

Built-in tools (always available):
- web_search / WebSearch (agent built-in)
- fetch / browser (agent built-in, if available)

text

### Build the active tool chain

Based on what's available, build the search chain for this session:

ACTIVE TOOL CHAIN:
[x] ref_search_documentation -> use as primary (Mode A)
[x] ref_search_codebase -> use for Mode B
[ ] context7 -> SKIP (not available)
[x] exa_search -> use as fallback
[ ] searchGitHub -> SKIP (not available)
[x] web_search (built-in) -> use as last resort fallback

Degraded mode: NO (MCP tools available)
-- OR --
Degraded mode: YES (no MCPs — will use built-in web_search only)

text

### Degraded mode (no MCPs available)

If NO MCP tools are available, proceed with built-in web search:
- Use `web_search` / `WebSearch` built-in tool for all searches
- Quality will be lower than MCP tools but skill remains fully functional
- Log: "Running in degraded mode — no MCPs available, using built-in web search"

**Do NOT abort the skill if MCPs are missing.** Always continue with whatever tools are available.

---

## Mode Selection

**Use Mode A when:**
- You need official documentation for a library/framework
- The technology is external (not in your codebase)
- You need latest changelogs, migration guides, or blog posts
- Trigger words: "research docs", "fetch docs", "official docs", "doc research"

**Use Mode B when:**
- You have repos already indexed on Ref.tools
- You want to find patterns from your own codebase
- Trigger words: "use ref codebase", "search my repos", "ref indexed", "codebase search"

**Use both (recommended for complex tasks):**
- Run Mode B first to find existing patterns, then Mode A to fill gaps
- Trigger: "full research", "complete doc research"

---

## MCP Tool Stack — Mode A (Online Docs Chain)

Use tools in this priority order. Skip unavailable tools and move to next.

| Priority | Tool | Available? | Fallback |
|----------|------|-----------|---------|
| 1 | `ref_search_documentation` + `ref_read_url` (Ref MCP) | Check Step -1 | → 2 |
| 2 | `context7_resolve-library-id` + `context7_get-library-docs` (Context7) | Check Step -1 | → 3 |
| 3 | `exa_search` + `exa_get_contents` (Exa MCP) | Check Step -1 | → 4 |
| 4 | `searchGitHub` (Grep/Morph MCP) | Check Step -1 | → 5 |
| 5 | `perplexity_search` (Perplexity MCP) | Check Step -1 | → 6 |
| 6 | `web_search` / `WebSearch` (built-in) | **Always available** | — |

---

## MCP Tool Stack — Mode B (Ref Codebase Search)

| Tool | Purpose | If unavailable |
|------|---------|---------------|
| `ref_search_codebase` | Search indexed repos for patterns | STOP Mode B, inform user to configure Ref MCP |
| `ref_read_url` | Read full file content | Skip — use summary from search results |
| `ref_search_documentation` | Search indexed doc sources | Skip if unavailable |

**If `ref_search_codebase` is not available:** Mode B cannot run. Inform user:
Mode B requires Ref MCP with indexed repos.
See rule-mcp-REF--USAGE--RIFARE.txt for setup.
Switching to Mode A instead.

text

---

## Step 0: Detect Mode

At the start of the skill, determine which mode to use:

If user prompt contains: "use ref", "ref codebase", "search my repos", "ref indexed", "codebase search"
→ MODE B (requires ref_search_codebase — check Step -1 result)
Else if user prompt contains: "full research", "complete research", "both"
→ MODE A + MODE B
Else
→ MODE A (default)

text

Confirm with user:
Tool check: [N] MCP tools available / [N] built-in tools
Mode selected: [A / B / A+B]
Tasks to process: #[ID1], #[ID2], ...
Proceed? (yes / change mode)

text

---

## Step 1: Identify Target Tasks

### 1a. If user specified task IDs in the prompt:
Use those IDs directly.

### 1b. If user said "all tasks" or no specific IDs:
Read `.taskmaster/tasks/tasks.json`:

```bash
task-master list
Research queue criteria (any of these = include):

Task mentions a specific library, framework, or external API

Task has apiVolatility: high in its details

Task involves: auth, payments, AI frameworks, database ORMs, external services

Task description is vague (< 50 words) and involves external dependencies

Skip criteria (all of these = skip):

Pure UI/styling with no external dependencies

Simple CRUD with well-known patterns

Task already has detailed doc references in its details field

1c. Confirm with user
text
Doc research queue:
  Task #3: [title] — needs: [technology/library]
  Task #5: [title] — needs: [technology/library]
Skipped: Task #1, #2, #4 (no external dependencies)
Proceed? (yes / adjust list)

Step 2: For Each Task — Extract Research Topics
bash
task-master show --id=TASK_ID
Extract:

Primary technology: main library/framework/API

Secondary technologies: dependencies, integrations

Specific features needed: which APIs, methods, patterns

Version constraints: if mentioned in PRD or tasks.json

Step 3A: Search Documentation (Mode A — Online Docs Chain)
Execute the chain using only tools confirmed available in Step -1.

3A-1. Ref MCP (if available)
text
ref_search_documentation(query="[technology] [specific feature]")
ref_read_url(url="[most relevant result URL]")
3A-2. Context7 (if available, Ref unavailable or insufficient)
text
context7_resolve-library-id(libraryName="[library]")
context7_get-library-docs(context7CompatibleLibraryID="[id]", topic="[feature]")
3A-3. Exa MCP (if available)
text
exa_search(query="[technology] [feature] documentation guide", num_results=5)
exa_get_contents(ids=["url1", "url2"])
3A-4. searchGitHub (if available)
text
searchGitHub(query="[specific API call pattern]", language="[typescript|python]")
3A-5. Built-in web search (always available — use if all MCPs unavailable)
text
web_search("[technology] [feature] official documentation site:[docs-url]")
web_search("[technology] [feature] best practices 2025")
When using built-in web search only:

Be more specific in queries to compensate for lower precision

Search for official docs URL first, then fetch content

Cross-reference at least 2 sources

Step 3B: Search Documentation (Mode B — Ref Codebase Search)
Requires ref_search_codebase (confirmed in Step -1).

3B-1. Codebase search
text
ref_search_codebase(query="[technology] [specific feature or API]")
Examples:

text
ref_search_codebase(query="Mastra agent tool registration")
ref_search_codebase(query="Prisma transaction pattern")
ref_search_codebase(query="Stripe payment intent create")
3B-2. Read relevant files
text
ref_read_url(url="[file URL from search result]")
3B-3. Synthesize codebase findings
Extract:

Existing implementation pattern in your repos

Team conventions (naming, file structure, config style)

Already-solved gotchas

Test patterns for this technology

Step 3AB: Combined Search (Mode A+B)

1. Run Step 3B first — establishes existing patterns

2. Run Step 3A — fills gaps with official docs

3. In doc file: clearly separate "From your codebase" vs "From official docs"

Step 4: Synthesize and Create Doc File
Filename format: doc/task-[ID]-[technology-slug].md
bash
mkdir -p doc
Use template in references/doc-output-template.md.

Mode B addition — add before "Official Documentation Links":

text
## Patterns from Your Codebase (Ref Indexed Search)
**Repos searched:** [list]
### Existing Implementation Pattern
[code snippet]
**File:** [repo/path/to/file.ts]
### Your Team's Conventions
- [convention 1]
### Already-Solved Gotchas
- [issue + solution]

Step 5: Update tasks.json with Doc References

bash
task-master update-task --id=TASK_ID --prompt="Add doc references to details:

## Doc References
- [doc/task-[ID]-[technology-slug].md] -- [technology]: [one-line description]

## Implementation Notes (from doc research)
[2-3 key notes]
Key API: [most important API call/pattern]
Watch out for: [most critical gotcha]
Codebase pattern: [if Mode B — reference to existing pattern]"


Via MCP:

text
update_task(id=TASK_ID, prompt="Add doc references to details:\n\n## Doc References\n- [doc/task-N-technology-slug.md] -- [tech]: [description]\n\n## Implementation Notes\n[key notes]")
Step 6: Verify and Report
bash
ls doc/
task-master show --id=TASK_ID
Report to USER (concise):

text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DOC RESEARCH COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Mode: [A / B / A+B]
Tasks processed: [N] | Doc files created: [N]
  doc/task-3-prisma-transactions.md
  doc/task-5-mastra-agent-patterns.md

Tasks updated: Task #3 (1 ref), Task #5 (2 refs), Task #7 (1 ref)
Skipped: Task #1, #2, #4 (no external deps)

--- Tools used ---
MCP:      [ref_search_documentation, exa_search] / none
Built-in: [web_search] / none
Mode B repos: [repo-name-1, repo-name-2] / n/a
Degraded mode: [yes / no]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next: USER reviews tasks.json
      → Fase 3: skill-parallel-wave-report
      → skill-github-project-issue-manager
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 7: Enrich Existing /doc Folder (if already present)
If doc/ exists from a previous run:

Existing file for same task+technology: update (append findings, update date)

No existing file: create new

Never delete existing doc files

Rules
NEVER abort because MCPs are missing — always fall back to built-in web search.

NEVER create doc files without updating the corresponding task's details field.

NEVER put full doc content in tasks.json — only references and key notes.

ALWAYS run Step -1 (tool discovery) before any search.

ALWAYS report which tools were used (MCP vs built-in) in Step 6.

Mode A: use Ref MCP first, fall back down the chain as needed.

Mode B: requires ref_search_codebase — if unavailable, switch to Mode A and inform user.

Doc filename format MANDATORY: doc/task-[ID]-[technology-slug].md (slug = technology name, not task title)

If requiresDocCheck: true in PRD: this skill is MANDATORY for that task.

If doc/ folder doesn't exist: create it with mkdir -p doc. Never fail because folder is missing.

Prefer 2024-2025 content over older posts when using web search.

Run once per task — NOT in batch mode (too slow and context-heavy).