---
name: explore-investigating-a-codebase
description: Use when planning or designing features and need to understand current codebase state, find existing patterns, or verify assumptions about what exists; when design makes assumptions about file locations, structure, or existing code that need verification - prevents hallucination by grounding plans in reality
---

# Investigating a Codebase

## Overview

Understand current codebase state to ground planning and design decisions in reality, not assumptions. Find existing patterns, verify design assumptions, and provide definitive answers about what exists and where.

## Scope

"The codebase" means the current project: the repo or working directory you were invoked in. Stay inside it unless you were specifically asked to explore elsewhere. Sibling directories, other repos on the machine, and anything else under the user's home belong to other projects; reading them pulls unrelated code into this project's design and quietly couples the two.

Two things are in scope beyond the project root: a path your prompt named explicitly, and the source of a dependency this project already declares (`vendor/`, `node_modules/`, the module cache).

A new or empty project has no patterns to find, and "no pattern exists here yet" is a real finding. Report it and let the caller decide where conventions should come from.

## When to Use

**Use for:**
- Verifying design assumptions before implementation ("Design assumes auth.ts exists - verify")
- Finding existing patterns to follow ("How do we currently handle API errors?")
- Locating features or code ("Where is user authentication implemented?")
- Understanding component architecture ("How does the routing system work?")
- Confirming existence definitively ("Does feature X exist or not?")
- Preventing hallucination about file paths and structure

**Don't use for:**
- Information available in external docs (use internet research)
- Questions answered by reading 1-2 specific known files (read them directly)
- General programming questions not specific to this codebase

## Core Investigation Workflow

1. **Start with entry points** - main files, index, package.json, config
2. **Use multiple search strategies** - file patterns, content search, and targeted reads
3. **Follow traces** - imports, references, component relationships
4. **Verify don't assume** - confirm file locations and structure
5. **Report definitively** - exact paths or "not found" with search strategy

## Verifying Design Assumptions

When given design assumptions to verify:

1. **Extract assumptions** - list what design expects to exist
2. **Search for each** - file paths, functions, patterns, dependencies
3. **Compare reality vs expectation** - matches, discrepancies, additions, missing
4. **Report explicitly**:
   - ✓ Confirmed: "Design assumption correct: auth.ts:42 has login()"
   - ✗ Discrepancy: "Design assumes auth.ts, found auth/index.ts instead"
   - \+ Addition: "Found logout() not mentioned in design"
   - \- Missing: "Design expects resetPassword(), not found"

**Why this matters:** Prevents project plans based on wrong assumptions about codebase structure.

## Quick Reference

| Task | Strategy |
|------|----------|
| **Where is X** | Match likely file names → search keywords → read matches |
| **How does X work** | Find entry point → follow imports → read implementation |
| **What patterns exist** | Find examples → Compare implementations → Extract conventions |
| **Does X exist** | Multiple searches → Definitive yes/no → Evidence |
| **Verify assumptions** | Extract claims → Search each → Compare reality vs expectation |

## Investigation Strategies

**Multiple search approaches:**
- Search file names and paths across the codebase
- Search contents for keywords, function names, and imports
- Read key files to understand implementation
- Follow imports and references for relationships
- Check package.json, config files for dependencies

**Don't stop at first result:**
- Explore multiple paths to verify findings
- Cross-reference different areas of codebase
- Confirm patterns are consistent not one-off
- Follow both usage and definition traces

**Verify everything:**
- Never assume file locations; always verify with file search and targeted reads
- Never assume structure - explore and confirm
- Document search strategy when reporting "not found"
- Distinguish "doesn't exist" from "couldn't locate"

## Reporting Findings

Return findings in the response. Do not create reports or other files unless the caller names a specific output path.

**Lead with direct answer:**
- Answer the question first
- Supporting details second
- Evidence with exact file paths and line numbers

**Provide actionable intelligence:**
- Exact file paths (src/auth/login.ts:42), not vague locations
- Relevant code snippets showing current patterns
- Dependencies and versions when relevant
- Configuration files and current settings
- Naming, structure, and testing conventions

**Handle "not found" confidently:**
- "Feature X does not exist" is valid and useful
- Explain what you searched and where you looked
- Suggest related code as starting point
- Report negative findings prevents hallucination

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Assuming file locations | Always verify with file search and targeted reads before reporting |
| Stopping at first result | Explore multiple paths to verify findings |
| Vague locations ("in auth folder") | Exact paths (src/auth/index.ts:42) |
| Not documenting search strategy | Explain what was checked when reporting "not found" |
| Confusing "not found" types | Distinguish "doesn't exist" from "couldn't locate" |
| Skipping design assumption comparison | Explicitly report: confirmed/discrepancy/addition/missing |
| Reporting assumptions as facts | Only report what was verified in codebase |
| Widening the search past the project root | Report "not found in this project" — the caller decides whether to look elsewhere |