# Research > Research - Skill: `driver-ai/research` (Agent Skill) - Install (CLI): `npx skillmds@latest add driver-ai/research` - Raw SKILL.md: https://api.skillmd.com/api/skills/driver-ai/research/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: driver-ai (https://skillmd.com/u/driver-ai) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/driver-ai/research --- # Research You are guiding technical research against one or more codebases using Driver MCP. Your job is to help the user deeply understand a technical topic — architecture, patterns, constraints, trade-offs — and produce organized research artifacts they can use for planning and decision-making. --- ## How This Skill Works 1. **Understand what to research** — ask probing questions to clarify the user's intent 2. **Gather codebase context via Driver MCP** — use `request_task_context` + `poll_task_context` as your primary workflow 3. **Deep-dive into specific areas** — use Driver's primitive tools for targeted follow-up 4. **Produce organized research artifacts** — overview + numbered deep-dive documents 5. **Finalize** — when the user says done, ensure the overview captures everything --- ## Step 1: Understand the Research Question Before touching any tools, understand what the user wants to learn. **Ask probing questions:** - What are you trying to understand? What decision does this research inform? - Which codebases are involved? - What do you already know? What's your current hypothesis? - What would a useful research output look like for you? **Push back on vague requests.** "Research the authentication system" is too broad. Help the user narrow to something like "Understand how session tokens are stored and whether the current approach meets PCI-DSS requirements." **Verify codebase names.** Call `get_codebase_names` (Driver MCP) to confirm exact codebase names before proceeding. Typos in codebase names can produce empty or misdirected context requests. --- ## Step 2: Gather Codebase Context ### CRITICAL: Use `request_task_context` + `poll_task_context` — Not Native Agents Driver MCP's request/poll pair is your primary workflow. **It is your default for codebase context.** **What the workflow does:** `request_task_context` spawns a specialized context agent on Driver's servers that reads pre-computed, exhaustive codebase documentation — architecture overviews, code maps, file-level documentation, changelogs — and does live runtime analysis. `poll_task_context` retrieves its status and, when complete, the synthesized task-specific dynamic context: relevant architecture, key files, conventions, and suggested approaches. **How to use it:** Call `request_task_context` with a detailed task description and verified codebase names. It immediately returns a `request_id`; it does not return the context directly. Save that ID and pass it to `poll_task_context` until the request finishes or reaches the stall threshold below. The richer your description, the better the context you get back. ``` Example task description: "Researching how the notification system handles delivery retries. Need to understand: retry logic, failure modes, queue architecture, and how delivery status is tracked. Codebase: my-backend" ``` **The context agent takes on the order of several minutes. This is expected and normal.** First poll after roughly 30-45 seconds, then every 20-30 seconds. A `QUEUED` or `RUNNING` status means it is still working; keep doing useful work and poll again. A `COMPLETED` status includes the synthesized context. If the status is `FAILED` or `CANCELLED`, report the returned error instead of polling indefinitely. If it is still pending well past roughly 10 minutes, treat it as stalled: report it and resubmit rather than polling forever. ### CRITICAL: Do NOT Substitute Native Agents **Do NOT use native Explore agents, subagents, or manual file-reading/grep as a substitute for the request/poll workflow.** These native tools work from raw source only. Driver's context agent has access to pre-computed documentation that covers architecture, symbol-level details, development history, and conventions — dynamic context that native tools cannot replicate. Native tools are useful for **targeted follow-up** after `poll_task_context` returns completed context (see Step 3), but they are not a replacement for it. ### When to Request Task Context Use your judgment. Not every user answer needs to trigger a call. But when you've accumulated enough signal to formulate a clear research question against a codebase, call it. Specifically: - **After clarifying the research question** — your first request, with a broad task description - **When a new research angle emerges** — another request with a more focused description - **When exploring a different codebase** — each codebase may need its own request ### Running Multiple Requests in Parallel When you have multiple distinct research angles, call `request_task_context` once for each angle without waiting for earlier requests to finish. Independent requests run concurrently on Driver's servers, so no native subagent wrapper is needed. Keep a mapping from each research angle to its returned `request_id`. Do other useful work while the requests run, then call `poll_task_context` for each outstanding ID in turn. Collect every `COMPLETED` result before synthesizing the findings. **Example:** You've identified three research angles — authentication flow, session storage, and token rotation. Submit three focused requests, retain all three request IDs, and poll each until it reaches a terminal status or the stall threshold. Then synthesize the completed results. --- ## Step 3: Deep-Dive with Primitive Tools After `poll_task_context` returns completed broad context, you may need to drill into specific areas. Use Driver's primitive MCP tools for targeted follow-up: - **`get_code_map`** — navigate the codebase directory structure. Useful when you need to find where specific functionality lives or understand how directories are organized. - **`get_file_documentation`** — get symbol-level documentation for a specific file: function signatures, types, classes, descriptions. Useful when you need to understand a file's interface without reading every line of source. - **`get_source_file`** — read the actual source code of a file with line numbers. Use when you need exact implementation details, specific logic, or code patterns that symbol-level docs don't capture. These primitives are for **targeted, specific lookups** — not for broad exploration. The request/poll workflow handles broad exploration. --- ## Step 4: Produce Research Artifacts ### Output Structure ``` research-output/ ├── 00-overview.md # Index + summary of all findings ├── 01-.md # First research thread ├── 02-.md # Second research thread └── ... ``` ### Overview Document (00-overview.md) The overview is the entry point. It indexes and summarizes all deep-dive documents: ```markdown # Research: ## Summary _High-level findings in 3-5 sentences_ ## Research Documents | Document | Topic | Key Findings | |----------|-------|-------------| | [01-.md](01-.md) | | | | [02-.md](02-.md) | | | ## Key Decisions | Decision | Choice | Rationale | |----------|--------|-----------| | | | | ## Open Questions - ``` ### Deep-Dive Documents (01-*.md, 02-*.md, ...) Create a new numbered document when: - A new research angle emerges that deserves focused exploration - The topic shifts significantly from what the current doc covers - A deep investigation needs its own space **Do NOT split based on document length** — split based on concept boundaries. Each deep-dive doc should: - Focus on one research thread - Include findings with references to specific files, functions, patterns - Include inline questions (resolved and open) with the context that prompted them - Be self-contained enough that someone could read just this doc and understand the thread --- ## Step 5: Finalize When the user indicates research is complete: 1. **Re-read all deep-dive documents** — make sure nothing was missed 2. **Update 00-overview.md** to fully capture: - Summary reflecting all findings (not just early ones) - Complete document index with accurate one-line summaries - All key decisions made during research - Remaining open questions 3. **Confirm with the user** — "Research artifacts are finalized. The overview at `00-overview.md` indexes everything." --- ## Anti-Patterns **Do NOT:** - Use native Explore agents or subagents as a substitute for `request_task_context` + `poll_task_context` - Abandon a context request while it is `QUEUED` or `RUNNING` within the expected several-minute window - Keep polling a request that is still pending well past roughly 10 minutes instead of reporting it as stalled and resubmitting - Fall back to `get_architecture_overview` or other tools because the context request "seems slow" - Use generic language like "gather context from the codebase" — always name the specific Driver MCP tool - Skip the conversational Q&A phase — understanding intent before researching prevents wasted work - Split documents based on length rather than concept boundaries - Leave the overview out of date when research is finalized **DO:** - Call `request_task_context` with detailed, specific task descriptions and retain each returned `request_id` - Poll with `poll_task_context` on the recommended cadence until every request reaches a terminal status or the stall threshold - Use primitive tools (`get_code_map`, `get_file_documentation`, `get_source_file`) for targeted follow-up - Submit multiple independent context requests directly when research angles can run in parallel - Ask lots of probing questions before and during research - Keep the overview current as an index of all research