Codebase Research

research — Plan stage (goal-blind codebase map)

Purpose

Stage: Plan (first skill; the human owns Plan). Produce one file — docs/features//research.md — a compressed, fact-only description of how the relevant code works today: call graphs, data shapes, external-API behavior, installed packages, prior art already present. It is NOT a design, a recommendation, or a comparison of options. If a sentence could be argued with, it does not belong. The test of a good research.md: a reader who has never seen the problem can verify every claim against the actual codebase or external docs.

Why this is its own goal-blind stage (three first-principles reasons):

1. Objectivity via goal-hiding. Telling a research context what you are building contaminates it —

it surfaces files that support the intended change and quietly ignores files that don't. The fix is structural, not disciplinary: research runs seeing only a sanitized problem statement, so objectivity is enforced by plumbing instead of willpower.

1. Research is the most leveraged stage. A bad line of code is one bad line. A bad line in the plan is

~100 bad lines of code. A bad line of research — a misunderstanding of how the codebase actually works — cascades into thousands. Errors here are the most expensive; that is why it gets its own context and its own artifact.

1. Focus without contamination. The sanitized problem statement supplies scope; the prd's Solution /

Implementation sections and every design substrate (ADRs, design.md, acceptance.md) are fenced out so the map stays objective.

When to use / when to skip

Use at the start of Plan, after the Spec gate signs prd.md, before plan-breakdown writes plan.md. Trigger words: "research the codebase," "do the codebase dive," or moving a feature from Spec into Plan.

Skip only a true greenfield repo with no relevant prior code — write ## Prior art in the codebase as _none_ — greenfield and let plan-breakdown proceed. Do not skip because the change "looks small": shallow research that stops at the first matching file is the named failure mode that sinks plans.

Inputs

Resolve the one required input in this order; refuse-to-run (naming the missing input) if none resolve:

1. Sanitized problem statement — one paragraph describing the user-facing outcome with implementation

direction stripped. "Users need to reset their password via email" is fine; "Add a /reset route that calls sendResetEmail() via SendGrid" is not — it leaks design.

• (a) inline in the invocation prompt, OR
• (b) derived from docs/features//prd.md by reading the ## Problem section only,

then rewriting it as a user-facing outcome with any solution verbs, package names, route names, and file paths stripped.

Objectivity fence — disallowed in the research context (the house equivalent of cr's "read only the goal line"): the prd's ## Solution / ## Implementation Decisions / ## Testing Decisions sections; ADRs and design.md; acceptance.md; any plan.md or slices; prior conversation history. The parent context must not read these before dispatch — reading them here contaminates every sub-agent prompt you assemble, and the goal-contamination you split this stage out to prevent comes right back.

Process

1. Resolve the sanitized problem statement per ## Inputs. Refuse-to-run if it cannot be resolved.
2. Dispatch research sub-agents in parallel (## Research sub-agents) — one turn, parallel tool calls.

Each gets the sanitized problem statement embedded directly; none read prd Solution/Implementation, ADRs, acceptance, plan, or tickets.

1. Wait for all sub-agents to return — no partial synthesis (whichever finishes first would bias the

doc).

1. Run the objectivity self-check (## Objectivity self-check) over every sub-agent output.
2. Synthesize into docs/features//research.md using the template in ## Output template.
3. Announce: Research complete for : files mapped, open items. Ready for plan-breakdown.

Research sub-agents (dispatch in parallel)

Dispatch one sub-agent per topic in a single turn with parallel tool calls (READ sub-agents may parallelize freely; the orchestrator's parallel-dispatch discipline applies — see ## References). Each sub-agent's prompt embeds the sanitized problem statement, the expected output shape (its section of the template), and the explicit instruction: "Do not read prd Solution/Implementation, ADRs, acceptance, or plan files. Do not make recommendations. Report only what exists."

Typical topics for a production feature:

1. Codebase-map agent — Grep for files in the relevant subsystem; Read the top 5–10; map the call

graph; chase imports and callers until the slice bottoms out. A map that stops at the first matching file fails the depth bar.

1. Dependency-facts agent — Read package.json / pyproject.toml / go.mod; list installed versions

of in-domain packages. No recommendations; just what is installed today.

1. External-API agent — If the domain touches an external service, fetch its docs; record auth

mechanism, rate limits, error codes, webhook shapes. Raw facts only — not "how we would call it."

1. Prior-art agent — Search the codebase (and, if warranted, widely-used OSS) for existing patterns

that solve structurally similar problems; record what was found and where. Do not rank or compare.

Model: default each sub-agent to sonnet — research is searching-and-summarizing, not reasoning-heavy, and sonnet keeps the parallel fan-out cheap without degrading fact quality. Escalate a single agent to the most capable model only when its domain is genuinely novel (e.g., an unfamiliar API with a complex state machine).

Objectivity self-check

Before synthesizing, scan every sub-agent output for recommendation verbs: should, recommend, prefer, we could, the best option, ideal. Rewrite or delete any sentence that contains one. If a sub-agent produced a comparison or a pros/cons list, drop it and surface the raw facts underneath. Alternatives live in the plan, not here.

Output template

# Research — 

## Codebase map
- Files in scope: 
- Entry points: 
- Call graph summary: 
- Existing invariants observed: 

## Dependency facts
- Installed packages in this domain: 
- Transitive pins that matter: 

## External APIs
- : auth=, rate-limit=, error-codes=, webhook-shape=

## Prior art in the codebase
- : used at ; shape: 

## Open items for Plan
- 

Sections with nothing in them go in as _none_ — don't delete them; the shape is part of the contract.

Rationalizations

• "Reading the prd's Solution section will help the sub-agents focus." No — that is exactly the

goal-contamination this stage exists to prevent. Focus comes from the sanitized problem statement, which was written to be the only thing research needs.

• "This change is small, I can skip the deep dive." Shallow research that stops at the first matching

file is a named failure (a real codebase attempt failed precisely because research never followed the dependency tree). Chase the slice until it bottoms out.

• "I'll just note which library is better while I'm here." A single recommendation pre-commits the plan

to a direction. Record what exists; let plan-breakdown decide.

• "I can start synthesizing while the last agent finishes." Partial synthesis biases the doc toward

whichever agent returned first.

Red flags

• A sentence in research.md contains should / recommend / prefer / we could / best option /

ideal.

• A pros/cons or "option A vs option B" comparison anywhere in the file.
• The parent context — or any sub-agent — has read prd Solution/Implementation, ADRs, acceptance.md, or

any plan/slice.

• Sub-agents dispatched serially, or synthesis started before all returned.
• A codebase map that stops at the first matching file (no import/caller chasing).

Verification (ending criteria)

Done when ALL hold:

• docs/features//research.md exists with all five stable sections present (empty → _none_).
• Objectivity self-check passed: zero recommendation verbs, zero comparisons.
• Every claim is verifiable against the codebase or external docs — no opinion, no design.
• The announce line was emitted.

Outputs & handoff contract

• Output path: docs/features//research.md.
• Consumer: plan-breakdown (THE planner) grounds its concrete plan (real files, line-steps, exact

tests) on this factual map; the codebase-design / api-design referenced disciplines read it too.

• Stable sections the consumer depends on: ## Codebase map, ## Dependency facts, `## External

APIs, ## Prior art in the codebase, ## Open items for Plan. Empty sections stay as none — the shape is the contract. **If you change the output shape, update plan-breakdown` in the same commit.**

• STATE.md: the feature stays in plan (Plan is human-led and in progress); record research.md

under the feature's origin: / artifacts. No slice rows yet — slices are born from plan-breakdown.

References

• Parallel-dispatch discipline (one turn, parallel calls; READ sub-agents parallelize freely; one writer

per file): the orchestrator skill + ~/.claude/rules/parallelism.md (mech b/f).

• Fresh-subagent-per-task discipline (the controller curates exactly what each sub-agent needs; the

sub-agent inherits nothing): superpowers:subagent-driven-development.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celestialdust
• Source: celestialdust/achilles-skills
• License: MIT

Install and usage instructions live in the source repository linked above.