improve-codebase-architecture
Improve Codebase Architecture
Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as GitHub issue RFCs.
A deep module (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside.
Working vocabulary
Use these terms exactly when describing architectural opportunities, in conversation with the user, in candidate write-ups, and in the resulting RFC issue. Do not drift into "component," "service," "API," or "boundary" — they read as synonyms but each one hides a different design decision and the slippage compounds across recommendations.
- Module — a unit of code that callers interact with through a stable interface. Files, classes, packages, or directories can all be modules; the test is whether something on the outside depends on something on the inside.
- Interface — the surface a module presents to callers: types, methods, parameters, return shapes, errors. Not the implementation.
- Implementation — the code behind the interface that callers do not see and should not depend on.
- Depth — the ratio of implementation hidden to interface exposed. Deep = a lot hidden behind a narrow surface; shallow = the interface is nearly as complex as the body.
- Seam — a place in the codebase where one module ends and another begins. Tests are written at seams; refactors move them.
- Adapter — a concrete implementation of an interface that bridges to a specific technology, transport, or external service. In-memory adapters serve tests; HTTP/SDK/queue adapters serve production.
- Leverage — how much downstream work a single change at this seam buys. Deepening a high-leverage module simplifies many callers; deepening a low-leverage one moves complexity around without saving anyone work.
- Locality — how much a reader must hold in working memory to understand a module. High locality = fewer files and fewer hops to grasp the behavior.
More from chrislacey89/skills
pre-merge
Primary pipeline review step after verified implementation. Use to create a PR with lineage and run architectural review before merge. Not for QA intake, planning, or implementation work.
22execute
Primary pipeline execution step after /prd-to-issues or for clearly scoped implementation work. Use to build, verify, and commit a concrete slice, delegating to /tdd for backend work and behavior-heavy frontend logic when red-green-refactor will reduce risk. Not for shaping or pre-merge review.
21write-a-prd
Primary pipeline shaping step after /research and before /prd-to-issues. Use when the problem is understood well enough to turn into a bounded PRD issue. May invoke /design-an-interface or /api-design-review when interface or contract uncertainty remains. Not for discovery, decomposition, or implementation-ready work.
14research
Primary pipeline step after /shape and before /write-a-prd. Use to verify current docs, versions, repo patterns, and key unknowns before shaping. Invokes /api-design-review when API contract risk is high. Not for underdefined problems or implementation-ready work.
13prd-to-issues
Primary pipeline decomposition step after /write-a-prd. Use when a shaped PRD is ready to become implementation-ready slices with boundary maps and dependency order. Not for unresolved scope, appetite, or solution direction.
13improve-pipeline
Optional meta-skill for improving `chrislacey89/skills` from real-world friction or breakdowns discovered while using the pipeline in another repo. Use when the main lesson is about the pipeline itself, not the downstream project. Grounds proposals in established software-engineering guidance from `/library`. Produces a GitHub issue in `chrislacey89/skills` and only moves to implementation after review.
12