codebase-understanding

name	codebase-understanding
description	CRG-first codebase navigation skill for all agents. Load when architecture must be traced, execution flow understood, impact radius determined, or entry points located before any implementation. Always queries code-review-graph before opening files — prevents blind file reads.
use-when	Load for any agent that needs to understand an unfamiliar system before working on it. Load at the start of bug investigation, feature design, or refactor planning. Load whenever an agent would otherwise start with broad Read/Grep/Glob.
do-not-use-when	Do not load when the task is a trivial change to a well-known file that requires no architecture investigation. Not needed for a quick comment fix or rename.
platforms	["claude-code","codex","copilot","cursor","windsurf"]
task-categories	["navigation","analysis","investigation","architecture"]
metadata	{"source":"internal","version":"1.0.0","tier":1}

Codebase Understanding — CRG-First

Core Rule

Query code-review-graph before reading any file. Never guess from filenames. Never grep blindly.

When to Use Each Agent

Task	Agent	First CRG Call
Understand system architecture	architecture-agent	get_architecture_overview
Read an unfamiliar feature	codebase-reader	get_minimal_context
Investigate a bug	bug-investigation	trace_execution_flow
Plan a refactor	refactor-agent	get_impact_radius
Implement a new feature	feature-dev-agent	find similar feature

CRG Tool Reference

Tool	Use Case
get_architecture_overview	Full system map before any analysis
trace_execution_flow	Follow what runs in what order
get_minimal_context	Orient around an unfamiliar symbol
find_entry_points	Where does this feature start?
list_related_symbols	What symbols participate in this feature?
trace_callers_callees	Who calls this? What does it call?
get_impact_radius	What breaks if I change this?
trace_dependencies	What does this depend on?
identify_shared_symbols	What is used by many callers?
identify_extension_points	Where does new code attach?

File Read Limit

Maximum 8 files per investigation, each justified by graph evidence.

Fallback (no CRG)

State "Running without CRG evidence" once. Use targeted Grep on known symbols. Read only files directly implicated. State your reasoning for each file opened.

Output Template

## Summary
<one paragraph>

## Execution Flow
<numbered steps>

## Relevant Systems
<list with ownership>

## Root Cause / Behavior
<precise statement>

## Impact Radius
<what would change if this is modified>

## Recommended Next Step
<single concrete action>