improve-codebase-architecture: Find Deepening Opportunities

Install this skill:

npx skills add mattpocock/skills skill=improve-codebase-architecture -y -g

Source: mattpocock/skills/improve-codebase-architecture

What it does

/improve-codebase-architecture looks for places where the codebase is hard to understand, hard to test, or hard for agents to navigate.

It does not start by proposing a rewrite. It looks for deepening opportunities.

A deep module puts useful behavior behind a small, stable interface. A shallow module makes callers learn almost as much as the implementation knows.

The language it uses

The skill is strict about architecture language:

Module: something with an interface and implementation
Interface: everything a caller must know to use the module
Implementation: the code inside
Depth: how much leverage the interface gives you
Seam: where behavior can change without editing in place
Adapter: a concrete thing satisfying an interface at a seam
Locality: keeping related change, bugs, and knowledge together

This shared language matters because vague architecture words create vague refactors.

When to use it

Use it after an agent run, a code review, or a planning session exposes friction.

Good signs:

understanding one concept requires bouncing through many files
tests only work by reaching into implementation details
helpers were extracted but did not make the system easier to change
the agent keeps choosing the wrong place to edit
the code works, but the workflow keeps producing avoidable mistakes

How it works

The skill reads the project's domain glossary and ADRs first.

Then it explores the codebase and proposes a numbered list of deepening opportunities. For each one, it explains:

which modules are involved
what friction exists today
what would change
how the change improves locality, leverage, and testability

Then you choose which candidate to explore.

How it fits the workflow

AFK agent finishes -> /review the diff -> improve the workflow -> improve the codebase

When an agent finishes, do not only ask whether the code works.

Ask why the agent made the mistakes it made. The answer might be weak instructions, vague issues, missing domain language, or architecture that hides the right path.

Fix the output, then improve the system that produced it.

Pairs well with

/grill-with-docs, to sharpen domain language before architecture work
/to-issues, to turn architecture improvements into thin reviewable slices
/review, to separate standards review from spec review