Improve Architecture
Explore a codebase organically, surface architectural friction, and propose refactors via GitHub issue RFCs. Uses "Design It Twice" — multiple parallel interface designs compared in prose.
Process
1. Friction-driven exploration
Use subagents to explore the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
- Understanding one concept requires bouncing between many small files
- Modules so shallow the interface is nearly as complex as the implementation
- Pure functions extracted just for testability, but real bugs hide in how they're called
- Tightly-coupled modules creating integration risk in the seams between them
- Untested or hard-to-test areas
- Code that fights you when you try to change it
The friction you experience IS the signal. Be honest about what confused you or slowed you down — that's the most valuable information.
2. Present candidates
Show a numbered list of opportunities. For each:
- Cluster: which modules/concepts are involved
- Why coupled: shared types, call patterns, co-ownership of a concept
- Dependency category: see references/dependency-categories.md
- Test impact: existing coverage, what boundary tests would replace
Don't propose solutions yet. Ask the user which candidate to explore.
3. Frame the problem space
For the chosen candidate, write up:
- Constraints any new interface must satisfy
- Dependencies it relies on
- A rough illustrative sketch to ground the constraints (not a proposal, just framing)
Show this to the user, then immediately proceed to step 4. The user reads while sub-agents work.
4. Design It Twice
Spawn 3+ sub-agents in parallel, each with a different design constraint and a separate technical brief (file paths, coupling details, dependency category, what's being hidden).
- Agent 1: Minimise the interface — 1-3 entry points max
- Agent 2: Maximise flexibility — support many use cases and extension
- Agent 3: Optimise for the most common caller — default case trivial
- Agent 4 (if applicable): Ports & adapters for cross-boundary dependencies
Each sub-agent outputs:
- Interface signature (types, methods, params)
- Usage example showing how callers use it
- What complexity it hides internally
- Dependency strategy (see references/dependency-categories.md)
- Trade-offs
Present designs sequentially, then compare in prose. Give an opinionated recommendation — which design is strongest and why. If elements combine well, propose a hybrid.
5. Create GitHub issue RFC
After the user picks a design (or accepts the recommendation), create a GitHub issue using gh issue create. Don't ask to review first — create and share the URL.
Use the RFC template:
## Problem
Describe the architectural friction:
- Which modules are shallow and tightly coupled
- What integration risk exists in the seams
- Why this makes the codebase harder to navigate and maintain
## Proposed Interface
The chosen interface design:
- Interface signature (types, methods, params)
- Usage example showing how callers use it
- What complexity it hides internally
## Dependency Strategy
Which category applies and how dependencies are handled:
- **In-process**: merged directly
- **Local-substitutable**: tested with [specific stand-in]
- **Ports & adapters**: port definition, production adapter, test adapter
- **Mock**: mock boundary for external services
## Testing Strategy
- **New boundary tests to write**: behaviours to verify at the interface
- **Old tests to delete**: shallow module tests made redundant
- **Test environment needs**: local stand-ins or adapters required
Replace, don't layer — old unit tests on shallow modules become waste once boundary tests exist. Delete them.
## Implementation Recommendations
Durable guidance NOT coupled to current file paths:
- 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