| name | improve-codebase-architecture |
| description | Scan a codebase for architecture friction and deepening opportunities. Use when Codex needs to audit old code, find shallow modules, improve testability, identify seams before implementation, or report architecture blockers without directly changing product code. |
Improve Codebase Architecture
Find architecture friction that blocks delivery, testability, or understanding. This skill reports options; it does not implement refactors unless the user explicitly asks afterward.
Use codebase-design vocabulary: module, interface, implementation, depth, seam, adapter, leverage, locality.
Read docs/agents/domain.md, docs/agents/verification.md, relevant CONTEXT.md, and ADRs when available.
Process
1. Scope The Audit
Anchor the scan to a request, PRD, issue, bug, audit finding, or code area. Avoid whole-repo wandering unless the user explicitly asks.
2. Explore Friction
Look for:
- Shallow modules whose interface nearly matches the implementation.
- Tests forced below the useful public interface.
- Logic scattered across callers.
- Hidden coupling across seams.
- Missing adapters where real variation already exists.
- Old code whose current behavior cannot be confidently accepted.
Use the deletion test and current verification commands.
3. Present Candidates
For each candidate, include:
- Module or area.
- Current friction.
- Proposed deeper module or seam.
- Benefits in leverage and locality.
- Testing or acceptance impact.
- Recommendation strength:
Strong, Worth exploring, or Speculative.
- ADR conflicts or domain language gaps.
For a visual report, use HTML-REPORT.md. Otherwise a concise markdown report is enough.
4. Recommend Next Step
Choose one:
- No architecture work needed before current slice.
- Prefactor first as its own verifiable issue.
- Include small design cleanup inside the first slice.
- Create a follow-up architecture issue after the bug or slice is fixed.
- Needs domain-modeling or ADR clarification.
Rules
- Do not make product code changes during the audit.
- Do not propose interfaces detached from a slice, bug, or acceptance concern.
- Do not relitigate ADRs unless real friction justifies reopening them.
- Prefer minimal architecture work that unblocks delivery and verification.
