research

Research

Objective codebase investigation that produces factual findings blind to the intent expressed in the discovery brief. The lead reads the brief and generates neutral questions. Teammates investigate the codebase. The lead compiles findings. No teammate ever sees the brief, the ticket, or the user's goals.

Environment

Agent teams: !echo ${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-disabled}

Prerequisites

1. If agent teams shows disabled above, stop immediately and tell the user:

   Agent teams are required for parallel research. Enable them by adding to your settings:

   { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
   

   Then restart the session.

   Teammates also need an interactive session. Under claude -p, a named spawn runs as an ordinary subagent — the waves still work, but findings return as subagent results instead of SendMessage.

2. Locate the brief:

   • Discovery handoff — the brief is already in conversation context. Use it directly.
   • Standalone invocation — $ARGUMENTS names a brief, or ask the user to provide one. Read it into conversation context — the skill works from context.
   • If no brief exists in conversation or on disk, ask the user whether to run discovery first.

Process

Phase 1 — Plan and Dispatch

1. Read the brief from conversation context.
2. Identify the codebase scope clusters the brief touches (modules, directories, subsystems).
3. For each scope, formulate the questions worth investigating. Follow the question generation rules below.
   • Multiple questions per scope is normal. Group questions that share files to avoid duplicate reads across teammates.
   • Don't fix a question count up-front. Let the brief's complexity determine how many.
   • The brief's Questions for research list (facts discovery deferred) is mandatory input — every entry becomes an investigation question, rewritten through the same neutrality rules as any other.
4. Self-check questions against the bias validation gate.
5. For each scope cluster, create a task via TaskCreate using the task description format below, then spawn one teammate via Agent with subagent_type: "codebase-researcher", name: "researcher-{scope-slug}", and an intent-free spawn prompt (see Spawn Prompt below).
   • The name is what makes the spawn a teammate, and it is the address other agents use to message it. There is no team to create — the session owns one team — and team_name is ignored.
   • Task descriptions contain only questions and scope boundaries. Never the brief, ticket, or intent.
   • Explicit subagent_type ensures the teammate inherits the agent's tool restrictions and system prompt; without it, the platform falls back to the general-purpose agent.
   • If this session has no Task tools, skip TaskCreate and put the task description block in the spawn prompt instead. It carries only questions and scope, so the information barrier holds.