researching-codebase

name	researching-codebase
description	Investigates codebase before planning. Use before any non-trivial implementation task to gather context in isolation.
argument-hint	["topic-or-question"]
context	fork
agent	Explore
allowed-tools	Read, Grep, Glob

Codebase Research (ACE-FCA)

Query: $ARGUMENTS

Gathers codebase context in isolation before planning. Prevents search artifacts from polluting main context.

Core Principles

1. Documentation-only - Describe what exists, where, and how it works
2. No evaluations - Never suggest improvements or critique implementation
3. Evidence-based - Provide file paths, line numbers, and code references
4. Isolation - Research runs in fork context; return only distilled findings

When to Use

• Before planning non-trivial implementations
• When unfamiliar with relevant codebase areas
• Before architectural decisions

Workflow

1. Read mentioned files first - If specific files mentioned, read completely before exploring
2. Decompose the question - Break query into researchable components
3. Explore codebase - Investigate architecture, patterns, constraints
4. Identify scope - Determine relevant areas based on findings
5. Distill - Return structured summary using output format below

Output Format

Follow ACE-FCA quality equation: Correct + Complete + Minimal noise

---
research_query: "<original question>"
timestamp: "<ISO 8601>"
files_examined: <count>
---

## Key Files

| File | Purpose | Key Lines |
|------|---------|-----------|
| `path/to/file.ext` | Brief purpose | L42-58 |

## Patterns

- **Pattern name**: Description with file reference (`path:line`)

## Constraints

- Constraint with evidence (`path:line`)

Evidence Requirements

Every claim must include:

• File path: Exact location (src/auth/login.ts)
• Line numbers: Specific lines (L42-58 or L127)
• Code reference: Function/class name when relevant

Bad: "Authentication uses JWT tokens" Good: "Authentication uses JWT tokens (src/auth/jwt.ts:L23-45, verifyToken function)"

References

See .claude/rules/context-management.md and .claude/rules/core-principles.md.