Overview

Codebase Research is a structured method to understand how an existing system works before diving into code. It follows the Iron Law: don't read files until the problem is understood, then uses file-finder and web-researcher agents to map data flows, constraints, and dependencies.

How This Skill Works

Begin by clarifying the request to define scope. Then explore the codebase with the file-finder agent in reading order, tracing data flows and constraints. Finally, document findings to docs/plans/YYYY-MM-DD-<topic>-research.md and use the web-researcher agent for external context when needed, before transitioning to planning or continued research.

When to Use It

• Implementation direction is clear but codebase understanding is needed
• Investigating how an existing feature works before modifying it
• Understanding dependencies and data flows before planning
• Gathering context for a known goal
• When external context is required to interpret code behavior

Quick Start

1. Step 1: Confirm understanding of the task with the user or stakeholder
2. Step 2: Use the file-finder agent to discover relevant files and read in suggested order
3. Step 3: Document findings to docs/plans/YYYY-MM-DD-<topic>-research.md and plan next steps or run external context checks with the web-researcher

Best Practices

• Ask clarifying questions before touching any file
• Use file-finder to establish a reading order and scope
• Trace data flows and identify core constraints
• Document findings in a timestamped plan file at docs/plans/YYYY-MM-DD-<topic>-research.md
• Only proceed to code exploration after human confirmation

Example Use Cases

• Clarifying a bug report's intent before scanning code paths
• Mapping data flow for a feature flag across services
• Reading a new microservice by following input/output boundaries
• Analyzing dependencies to assess refactor impact
• Creating a research brief to onboard a teammate to a code area

Frequently Asked Questions