/improve-codebase-architecture

Explore a codebase like an AI would, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs.

Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

A deep module has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside. (John Ousterhout, A Philosophy of Software Design)

The deepening test: would merging these modules produce a smaller combined interface than they have separately? If no, it's not a deepening opportunity — it's just reorganization.

Reference — Dependency Categories

Classify each candidate's dependencies; the category determines the entire testing strategy.

1. In-process — pure computation, in-memory state, no I/O. Always deepenable; merge and test directly.
2. Local-substitutable — dependencies with local test stand-ins (PGLite for Postgres, memfs for filesystem). Deepenable if the stand-in exists; test the merged module with the stand-in running in the suite.
3. Remote but owned (Ports & Adapters) — your own services across a network boundary. Define a port at the boundary; the deep module owns the logic, transport is injected. Tests use an in-memory adapter; production uses the real one.
4. True external (Mock) — third-party services you don't control (Stripe, Twilio). Mock at the boundary; the deepened module takes the external dependency as an injected port, tests provide a mock.

Reference — Testing Strategy

Replace, don't layer. Write new tests at the deepened module's interface boundary. Old unit tests on the now-merged shallow modules become redundant — delete them. Tests assert on observable outcomes through the public interface, not internal state, so they survive internal refactors.

Step 1 — Explore the codebase

Navigate organically. Note where you experience friction: where understanding one concept requires bouncing between many small files; where modules are so shallow the interface is nearly as complex as the implementation; where pure functions were extracted just for testability while the real bugs hide in how they're called; where tightly-coupled modules create integration risk at the seams; which parts are untested or hard to test. The friction you encounter IS the signal — don't follow rigid heuristics.

If you find no strong candidates, say so directly. A thin adapter over a stable external API is correct design, not a problem. Don't manufacture candidates — tell the user what you found and why the codebase resists the pattern.

Step 2 — Present candidates

⚠️ Deepening test: before listing a candidate, verify merging produces a smaller interface than the modules have separately. If not, it's reorganization — skip it.

For each genuine candidate show: Cluster (modules/concepts involved), Why they're coupled (shared types, call patterns, co-owned concept), Dependency category (one of four, one-sentence rationale), Test delta (specific test files that would be deleted, and the new boundary tests that replace them). Then ask: "Which of these would you like to explore?"

Step 3 — User picks a candidate

Step 4 — Frame the problem space

Write a user-facing explanation of the chosen candidate: the constraints any new interface must satisfy, the dependencies it must handle (with category), and a rough illustrative code sketch to make the constraints concrete (a grounding device, not a proposal). Show this, then immediately proceed to Step 5 — the user reads while designs are worked.

Step 5 — Design multiple interfaces

Produce 3–4 radically different interface designs, each under a different constraint:

• A — Minimal: 1–3 entry points max. Ruthlessly hide everything.
• B — Flexible: support many use cases and extension points; maximize what callers can customize.
• C — Caller-optimized: make the most common call site trivial; ergonomics over generality.
• D — Ports & Adapters (if applicable): design around injected adapters for cross-boundary dependencies.

Each design produces: (1) interface signature, (2) usage example, (3) what complexity it hides, (4) dependency strategy per category, (5) trade-offs.

⚠️ Don't mistake extraction for deepening. If a design has the same total interface surface as the original modules combined, it's a rename. The interface must get smaller.

Before dispatch, bind the worker and total invocation to finite deadlines and resource limits, with a named monitoring owner, observable progress, a cancellation handle and terminal success/failure/timeout outcomes. Use native controls; include read-only scope and no-child instructions in research briefs. On failure or timeout, cancel owned work and report retained partial results and unchecked coverage. If these controls are unavailable, do not dispatch. Use the existing bounded inline fallback when permitted, labeling it non-independent; empty or failed returns never count as completed coverage.

If sub-agents are available (Claude Code / Cowork): spawn 3–4 in parallel with the brief template below. Do not share prior designs between agents — isolation is the point. If not (Claude.ai): work each constraint sequentially, treating each design as complete before the next; this is useful but correlated same-context generation, not independent cold work.

## Design Brief

### Context
Codebase: [repo/language]
Candidate: [module cluster name]

### Files involved
[file path] — [one-line summary]

### Coupling description
[Why these modules are tightly coupled — shared types, call patterns, co-owned concepts]

### Dependency category
[In-process / Local-substitutable / Remote but owned / True external] — Rationale: [one sentence]

### What the deepened module should hide
[Internal state, wiring, error handling, retry logic, etc.]

### What it must expose
[The minimum surface callers actually need]

### Your design constraint
[One of: Minimal / Flexible / Caller-optimized / Ports & Adapters]

### Output format required
1. Interface signature  2. Usage example  3. What complexity it hides  4. Dependency strategy  5. Trade-offs

After all designs are presented, compare them in prose and give an opinionated recommendation — which is strongest and why, or a hybrid. The user wants a strong read, not a menu.

Step 6 — User picks an interface (or accepts the recommendation)

Step 7 — Create GitHub issue

Resolve and read back the exact destination repository with the complete issue draft before approval. Bind that approved repository explicitly in the publication command; ambiguous or changed identity stops publication. Draft the RFC using the template below. Render the complete draft as a markdown block in the conversation, then ask: "Should I create this issue now?" Wait for explicit confirmation before running gh issue create --repo <approved-owner/repository>. If gh is unavailable, print the final draft for manual paste.

## Problem
- Which modules are shallow and tightly coupled
- What integration risk exists at the seams
- Why this makes the codebase harder to navigate and maintain

## Proposed Interface
- Interface signature (types, methods, params)
- Usage example showing how callers use it
- What complexity it hides internally

## Dependency Strategy
[Category name] — [one sentence on how deps are handled]
- Production: [real adapter / merged module / mock boundary]
- Tests: [stand-in / in-memory adapter / mock implementation]

## Testing Strategy
- New boundary tests to write: [behaviors to verify at the interface — inputs and expected outcomes]
- Old tests to delete: [specific test file names and why they become redundant]
- Test environment needs: [stand-ins, adapters, or fixtures required]

## Implementation Recommendations
[Durable architectural principles, not file-path instructions.]
- What the module should own (responsibilities)
- What it should hide (implementation details)
- What it should expose (the interface contract)
- How callers should migrate to the new interface

Old tests to delete. Name specific old tests only when deletion is justified by a behavioral coverage mapping to retained/replacement boundary tests. An evidenced none is valid, including an untested candidate; do not manufacture a deletion list to satisfy the template.

⚠️ "Implementation Recommendations" must be file-path-agnostic. Write principles a future engineer can apply even after the codebase is reorganized.

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.