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/WebSearchbuilt-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:
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).