improve-codebase-architecture v1.0A

Immutable. This exact content is served forever at /api/v1/blob/1a486ba37e1fa20c.

---
name: improve-codebase-architecture
description: >
  Identify architectural friction and propose deepening opportunities — refactors
  that turn shallow modules into deep ones for better testability and AI-navigability.
  Use when improving architecture, finding refactoring opportunities, consolidating
  tightly-coupled modules, or making a codebase more testable.
allowed-tools: Read Grep Glob Bash Write Edit
compatibility: >
  Works best in codebases with CONTEXT.md domain documentation. Creates CONTEXT.md
  lazily when absent. Pairs with grill-with-docs for terminology refinement and
  code-refactoring for implementation.
metadata:
  tags: architecture, refactoring, deep-modules, testability, locality, leverage
  platforms: Claude, ChatGPT, Gemini, Codex
  version: "1.0"
  source: mattpocock/skills
---

# Improve Codebase Architecture

Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. Goal: testability and AI-navigability.

## Vocabulary (use these terms exactly)

- **Module** — anything with an interface and implementation (function, class, package, slice)
- **Interface** — everything a caller must know: types, invariants, error modes, ordering, config
- **Depth** — leverage at the interface: much behavior behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation
- **Seam** — where an interface lives; a place behavior can be altered without editing in place
- **Adapter** — a concrete thing satisfying an interface at a seam
- **Leverage** — what callers get from depth
- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place

**Key principles:**
- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- **The interface is the test surface.**
- **One adapter = hypothetical seam. Two adapters = real seam.**

## When to use this skill

- User wants architectural improvement opportunities
- Codebase is hard to navigate or test
- Modules feel tightly coupled or shallow
- Refactoring would improve testability

## When not to use this skill

- Quick targeted refactors → use `code-refactoring`
- Design review of a plan → use `grill-with-docs`
- Implementation tickets → use `to-issues`

## Process

### 1. Explore

Read domain glossary (`CONTEXT.md`) and ADRs first. Then walk the codebase organically, noting friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow** — interface nearly as complex as the implementation?
- Where have pure functions been extracted for testability, but real bugs hide in how they're called?
- Where do tightly-coupled modules leak across seams?
- Which parts are untested or hard to test through their current interface?

Apply the **deletion test** to suspected shallow modules.

### 2. Present candidates

Numbered list of deepening opportunities. For each:

- **Files** — which files/modules are involved
- **Problem** — why the current architecture causes friction
- **Solution** — plain English description of what would change
- **Benefits** — in terms of locality, leverage, and test improvement

Use `CONTEXT.md` vocabulary for domain terms. Use the vocabulary above for architecture terms.

**ADR conflicts**: if a candidate contradicts an ADR, only surface it when friction is real enough to warrant revisiting. Mark clearly: *"contradicts ADR-0007 — but worth reopening because…"*

Ask: "Which of these would you like to explore?" — do NOT propose interfaces yet.

### 3. Grilling loop

Once user picks a candidate, drop into a grilling conversation. Walk the design tree: constraints, dependencies, module shape, what sits behind the seam, what tests survive.

Side effects as decisions crystallize:
- **New concept not in CONTEXT.md?** Add the term immediately
- **Fuzzy term sharpened?** Update CONTEXT.md right there
- **User rejects with a load-bearing reason?** Offer an ADR (only when a future explorer would need it to avoid re-suggesting the same thing)