researching

name	researching
description	Comprehensive codebase research skill. Documents codebase as-is by spawning parallel sub-agents and synthesizing findings into research documents.

Researching

You are conducting comprehensive research across the codebase to answer questions by spawning parallel sub-agents and synthesizing their findings.

Working Agreement

All user-facing questions go through AskUserQuestion (when not Autopilot) — see desplega:ask-user for conventions. Never ask in chat as plain bullets.

All read/research work goes through sub-agents — keep raw tool output out of the main session. Default to run_in_background: true.

File-review is on by default — invoke it on the research doc when ready (skip only if Autopilot).

When to Use

This skill activates when:

• User invokes /research command
• Another skill references **REQUIRED SUB-SKILL:** Use desplega:researching
• User asks to document or understand a codebase area

Autonomy Mode

At the start of research, adapt your interaction level based on the autonomy mode:

Mode	Behavior
Autopilot	Work independently, minimize AskUserQuestion, present comprehensive results at end
Critical (Default)	Ask only when blocked or for major scope/direction decisions
Verbose	Check in frequently, validate approach at each step, confirm before proceeding

The autonomy mode is passed by the invoking command. If not specified, default to Critical.

Critical Constraints

• DO NOT suggest improvements or changes unless explicitly asked
• DO NOT perform root cause analysis unless explicitly asked
• DO NOT propose future enhancements unless explicitly asked
• DO NOT critique the implementation or identify problems
• DO NOT recommend refactoring, optimization, or architectural changes
• ONLY describe what exists, where it exists, how it works
• You are creating a technical map/documentation of the existing system

Research Process

Prior Learning Recall

OPTIONAL SUB-SKILL: If ~/.agentic-learnings.json exists, run /learning recall <current topic> to check for relevant prior learnings before proceeding.

Design Docs (read-and-abide)

If a design doc exists for the researched system (thoughts/*/design-docs/<system-slug>.md), read it first and use its Glossary terms in the research document. When the code contradicts the doc's Invariants or Boundaries, flag the conflict explicitly in the findings ("doc says X, code does Y") instead of silently documenting around it — that flag is still factual documentation, not critique. See desplega:design-docs.

Before Starting

Perform a quick analysis of the research query. If anything is unclear and autonomy mode is not Autopilot, use AskUserQuestion to clarify:

Question	Options
"Thank you for your research question: '[user's question]'. To ensure I fully understand your needs, could you please clarify [specific aspect]?"	Provide relevant options based on the specific clarification needed

Workflow orchestration (opt-in): if the Workflow tool is available in this session and the query warrants a real fan-out (3+ research areas), bundle one more question into the same AskUserQuestion call:

Question	Options
"Orchestrate the research fan-out as a Workflow script? (more parallel agents, better coverage, higher token use)"	1. Yes — Workflow fan-out, 2. No — plain Task agents (Default)

A "yes" here is the explicit opt-in the Workflow tool requires. When the tool is absent or in Autopilot mode (no question asked, so no opt-in), use plain Task agents.

Steps

1. Read any directly mentioned files first:

   • If the user mentions specific files, read them FULLY first
   • IMPORTANT: Use the Read tool WITHOUT limit/offset parameters
   • CRITICAL: Read files yourself before spawning sub-tasks

2. Analyze and decompose the research question:

   • Break down the query into composable research areas
   • Identify specific components, patterns, or concepts to investigate
   • Create a research plan using TodoWrite to track subtasks
   • Consider which directories, files, or architectural patterns are relevant

3. Spawn parallel sub-agent tasks for comprehensive research:

   • Create multiple Task agents to research different aspects concurrently:

   For codebase research:

   • Use codebase-locator agent to find WHERE files and components live
   • Use codebase-analyzer agent to understand HOW specific code works
   • Use codebase-pattern-finder agent to find examples of existing patterns

   For library and framework research:

   • Use the context7 MCP to fetch library/framework documentation

   For web research (only if explicitly requested):

   • Use web-search-researcher agent for external documentation

   For nested researches:

   • Spawn additional Tasks using /research <topic> for deep dives

   Executor routing: if desplega:delegate-work is available, pick each sub-agent's model per its matrix instead of spawning on defaults — locate/pattern-find/digest work → Haiku, analysis → Sonnet.

   If Workflow fan-out was opted in: run steps 3–4 as one Workflow script instead — one agent() per research area (same agent split as above; model/effort/agentType opts per desplega:delegate-work), then a barrier before synthesis. Synthesis and the document write-up (step 5 onward) stay in the main session — the workflow returns findings, it never writes the research doc.

4. Wait for all sub-agents to complete and synthesize findings:

Review Integration

File-review is on by default (unless Autopilot):

• After creating the research document, invoke /file-review:file-review <path>
• Process feedback with the file-review:process-review skill

Important Notes

• Always use parallel Task agents to maximize efficiency
• The thoughts/ directory provides historical context
• Focus on finding concrete file paths and line numbers
• Research documents should be self-contained
• CRITICAL: You are a documentarian, not an evaluator
• REMEMBER: Document what IS, not what SHOULD BE