| name | analyze-codebase |
| description | Analyze an existing repository in read-only mode to reconstruct current behavior, architecture, dependency clusters, build and test health, hotspots, tech debt, ownership boundaries, integration points, and current-vs-target gaps. Use for existing-product improvement, migration planning, code archaeology, risky refactors, unfamiliar repositories, or artifacts `80-current-state-scan.md` through `85-migration-plan.md` before writing code. |
Analyze Codebase
Role
Slow the impulse to edit until the system has been understood. Produce an evidence-backed map of what exists, how it behaves, and where change would be risky.
Start By
- Read the repo orientation files and build/test commands.
- List languages, frameworks, services, data stores, queues, and deployment pieces.
- Find entrypoints, critical flows, and ownership boundaries.
- Identify generated, vendored, or external code that should not be rewritten casually.
Procedure
- Map top-level directories to responsibilities.
- Trace the most important runtime flows from entrypoint to persistence or external boundary.
- Check build, test, lint, and local run instructions without changing source files.
- Identify hotspots: high-change files, large modules, unclear boundaries, test gaps, risky dependencies, and fragile contracts.
- Compare current architecture to the requested target and write migration risks before proposing edits.
- Stay read-only unless the user explicitly moves the work into implementation.
Principal-Level Defaults
- Follow
../../routing/principal-operating-model.md before moving from analysis to implementation.
- Use Context7 MCP for current library, framework, platform, API, CLI, and configuration documentation whenever the task depends on external technology behavior.
- Keep a decision trace: facts, assumptions, options considered, tradeoffs, selected path, validation evidence, and rollback or follow-up.
- Escalate irreversible, security-sensitive, data-migration, production, or cross-boundary choices before write-heavy work.
Output Artifacts
- Current-state scan
- Codebase map
- Hotspots and tech-debt list
- Current architecture summary
- Target gap notes
- Migration plan inputs
Quality Bar
- Back claims with file paths, commands, or observed behavior.
- Do not infer architecture from folder names alone.
- Separate actual current behavior from desired target behavior.
- Call out unknowns instead of smoothing them over.
Handoff
Hand off evidence, high-risk files, safe write boundaries, and validation commands to architecture or decomposition.
References
references/scan-checklist.md: Use this checklist when scanning an existing repository.
