Improving Codebase Architecture

Find evidence-backed structural improvements that concentrate behavior and ownership behind smaller, clearer interfaces. Treat review, assessment, diagnosis, and planning requests as read-only. Improvement, refactoring, or implementation requests authorize in-scope local edits and non-destructive validation. Require confirmation before external writes, destructive actions, an incompatible public API or data migration, or material scope expansion.

Establish Scope

1. Read repository instructions and the domain glossary, architecture documents, and ADRs relevant to the target. Missing optional architecture documents are not blockers.
2. Use the area, pain point, or behavior named by the user. Trace only its actual callers, contracts, dependencies, data and state ownership, tests, and directly affected runtime paths.
3. When no target is named, inspect recent change history and repeatedly modified paths to bias the assessment toward architecture where future work is likely. Widen the scan only when no meaningful hotspot emerges.
4. If multiple incompatible directions remain equally plausible, or the work would break a public API, require a migration, or cross the requested boundary, ask one focused question before choosing.

Assess

Load the architecture assessment reference when evaluating candidates.