Analyze Codebase
Purpose
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.
Inputs
- 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.
Decision process
- 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.
Decision boundaries
- Use Context7 MCP for current library, framework, platform, API, CLI, and configuration documentation whenever the task depends on external technology behavior.
Decision record
- Current-state scan
- Codebase map
- Hotspots and tech-debt list
- Current architecture summary
- Target gap notes
- Migration plan inputs
Ready when
- 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.
1---2name: analyze-codebase3description: 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.4---56# Analyze Codebase78## Purpose910Slow 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.1112## Inputs1314- Read the repo orientation files and build/test commands.15- List languages, frameworks, services, data stores, queues, and deployment pieces.16- Find entrypoints, critical flows, and ownership boundaries.17- Identify generated, vendored, or external code that should not be rewritten casually.1819## Decision process20211. Map top-level directories to responsibilities.222. Trace the most important runtime flows from entrypoint to persistence or external boundary.233. Check build, test, lint, and local run instructions without changing source files.244. Identify hotspots: high-change files, large modules, unclear boundaries, test gaps, risky dependencies, and fragile contracts.255. Compare current architecture to the requested target and write migration risks before proposing edits.266. Stay read-only unless the user explicitly moves the work into implementation.2728## Decision boundaries2930- Use Context7 MCP for current library, framework, platform, API, CLI, and configuration documentation whenever the task depends on external technology behavior.3132## Decision record3334- Current-state scan35- Codebase map36- Hotspots and tech-debt list37- Current architecture summary38- Target gap notes39- Migration plan inputs4041## Ready when4243- Back claims with file paths, commands, or observed behavior.44- Do not infer architecture from folder names alone.45- Separate actual current behavior from desired target behavior.46- Call out unknowns instead of smoothing them over.4748## Handoff4950Hand off evidence, high-risk files, safe write boundaries, and validation commands to architecture or decomposition.5152## References5354- `references/scan-checklist.md`: Use this checklist when scanning an existing repository.
ashermahonin