gs-improve-codebase-architecture

Installation
SKILL.md

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

The project's domain model informs this skill, and it builds on a shared design vocabulary:

  • Use gs-codebase-design when it is installed, for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter means a hypothetical seam, two means a real one"). Without it, use these definitions:

    • Module: anything with an interface and an implementation, from a function to a package.
    • Interface: everything a caller must know to use the module: types, invariants, ordering, error modes, configuration, and performance.
    • Depth: how much behaviour a caller can exercise per unit of interface. A deep module hides a lot behind a small interface. A shallow module's interface is nearly as complex as its implementation.
    • Seam: the place where a module's interface lives, where behaviour can change without editing that place.
    • Adapter: a concrete thing that satisfies an interface at a seam.
    • Leverage: what callers get from depth, more capability per unit of interface.
    • Locality: what maintainers get from depth, change and bugs concentrated in one place.
    • The deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it earned its keep.

    Use these terms exactly in every suggestion. Don't drift into "component," "service," "API," or "boundary."

  • When the project has a domain glossary (GLOSSARY.md), its terms name good seams. When it has ADRs in docs/adr/, they record decisions this skill should not re-litigate. A project may have neither.

Installs
2
First Seen
2 days ago