research

§ 01 · purpose

Purpose

Resolves ambiguities about how the existing implementation works *before* deciding how to change it. Subsequent design and planning skills read this artifact instead of re-reading the codebase, so downstream phases are grounded in evidence and start cheap.

§ 02 · when to use

When to use it

• You need depth on architecture or behavior questions before a change.
• A discover artifact exists and the team needs file-backed answers to its open questions.
• You're about to design or plan and want a single citation source.
• Skip if the area is already well-trodden and the change is a one-line fix.

§ 03 · inputs

Inputs

$ARGUMENTS

A discover artifact triggers FRD parsing — its Decisions become Developer Context.

§ 04 · outputs

Outputs

§ 05 · key steps

Key steps

1. 01 Trace the investigation scope Why: The scope-tracer agent reads the prompt, sweeps anchor terms, and emits 5–10 dense numbered questions. Locking scope before any deep read prevents agents from chasing a fuzzy target.
2. 02 Group related questions Why: Questions that share 2+ file references are grouped into a single agent dispatch so the agent can use cross-question context for deeper, more connected analysis — fewer agents, more depth per token.
3. 03 Dispatch analysis agents in parallel Why: One codebase-analyzer per question (or group), plus one web-search-researcher for external-doc questions and one precedent-locator when git history is available. All run concurrently; sync barrier before synthesis.
4. 04 Synthesize findings into a jump table Why: Final document is file:startLine-endLine references plus prose — not code blocks, not implementation recipes. Designed for the planner to look up, not re-read.
5. 05 Grounded developer checkpoint Why: One question at a time, every question embeds a real file:line reference. Pulls only NEW information from the developer; confirmatory questions are explicitly banned.

§ 06 · related skills

Related skills