| name | improve-codebase-architecture |
| description | Read-only audit of an EXISTING codebase for module-depth problems that make it hard for AI agents to work in. Surfaces shallow modules (leaky interfaces, many tiny files exporting internals), zero-test modules, and tightly-coupled clusters, then proposes deepening candidates with coupling rationale + a test-boundary recommendation. Produces a prioritized markdown report — NEVER auto-refactors. Grounded in Ousterhout's A Philosophy of Software Design (deep vs shallow modules) + the principle that test/feedback-loop quality sets the ceiling on AI coding quality (SWE-bench Verified). Use after /audit or /test-audit, before a big AI-assisted refactor, or when agents keep producing low-quality changes in one area. Triggers (CZ+EN) "/improve-codebase-architecture", "improve architecture", "deepen modules", "make this codebase agent-friendly", "why does AI write bad code in this repo", "shallow modules audit", "prohlub moduly", "zlepši architekturu", "proč tu AI píše špatný kód", "najdi shallow moduly". |
| disable-model-invocation | false |
/improve-codebase-architecture — make a codebase AI agents can work in
Voice charter: see standards/voice.md. Counts and findings, not praise. No emoji.
You are auditing an existing codebase for module depth (Ousterhout: deep = simple interface / lots of functionality; shallow = leaky interface / little functionality). The thesis: a codebase of deep, well-tested modules gives an AI agent a clean interface graph to navigate and fast feedback loops to code against; a codebase of shallow modules forces the agent to load implementation details into context and guess at test boundaries — which is the lever on agent output quality. See standards/modular.md § "Module depth for AI codeability".
This is a READ-ONLY audit. You produce a prioritized report. You do NOT refactor, edit source, or open PRs. The operator picks what to act on.
Phase 0 — locate the code
Detect the stack and the source roots (don't audit node_modules, dist, .next, vendor, generated files, or secret/config files — .env*, *.pem, *.key, lockfiles). Note the test framework + how tests map to source (co-located *.test.ts vs. a tests/ tree). If there's a cortex/AUDIT.md or repo-map.md from a prior /audit, read it for context first.
Phase 1 — scan for shallow-module signals
Walk the source tree and flag modules exhibiting these signals (each is a hint, not a verdict — weight them together):
- Leaky interface — a file/module that exports many symbols relative to the functionality behind them (barrel re-exports,
utils.ts with N unrelated helpers, types files exporting everything).
- Many tiny chunks — a folder of many <30-line files that only make sense read together (classitis); callers must understand all of them to use any.
- Zero-test modules — source with meaningful logic and no test boundary around it. This is the highest-priority signal: no test = no feedback loop = agent codes blind here.
- High coupling — a module that imports from / is imported by many others, or that reaches into another module's internals rather than its interface (reverse dependency, circular import).
- Interface ≈ implementation — a "module" whose interface surface is as large as its body (no information hiding; nothing is actually encapsulated).
Use Grep/Glob to gather evidence (import counts, export counts, file sizes, presence of a sibling test). Cite real file:line for every signal — never assert a pattern you haven't seen.
Phase 2 — cluster + rank deepening candidates
Group related shallow modules into deepening candidates — a cluster that could become one deep module with a single clean interface + one test boundary. For each candidate report:
- Modules involved (file paths) + the signals that flagged them.
- Coupling rationale — why these belong together (shared state, always-changed-together, one calls the others' internals).
- Proposed deep interface — the small surface the cluster should expose (1-line sketch, not a full design).
- Test-boundary recommendation — where to draw the test boundary, and whether substitutability is local (in-memory/SQLite) or needs a seam.
- Priority — P0 (zero-test + high-coupling on a critical path), P1 (zero-test or high-coupling), P2 (cosmetic shallowness, low risk).
Order by priority. Cap the report at the top ~7 candidates — a wall of findings is noise (see anti-patterns).
Phase 3 — write the report
Write cortex/architecture-audit.md in the project (create cortex/ if absent). Sections:
- Summary — N candidates found, breakdown by priority, the single biggest gap in one line.
- Deepening candidates — the Phase 2 list, P0 first.
- Quick wins — any zero-test deep-ish module that just needs a test boundary added (cheap, high feedback-loop payoff).
- What this audit did NOT do — restate: no refactor applied; operator picks targets.
Announce the artifact with one concrete line (path + candidate count). Then stop — do not start refactoring.
Out of scope (explicit)
- No auto-refactor. This skill never edits source or moves files. Deepening a module is a human-reviewed change (it alters interfaces — high blast radius). If the operator wants to act, that's a separate, scoped task.
- No metric theater. Don't invent a "depth score" number; the signals + rationale are the output. (Coupling metrics like fan-in/fan-out are evidence, not a grade.)
- No GraphRAG / full dependency graph build — that's deferred (roadmap Sprint 3.3). Use Grep/Glob evidence, not a heavyweight analyzer.
Composes with
/audit (12-dimension general audit) — run that first for repo context; this skill is the architecture-depth lens./test-audit (QA lens) — pairs naturally: zero-test modules surface in both; this one frames them as feedback-loop gaps.standards/modular.md — the standard this skill enforces.standards/context-engineering.md — why deep modules save agent context budget.
Sources
