| name | improve-codebase-architecture |
| description | Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable. |
Improve Codebase Architecture
Explore this codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as local issue RFCs under issues/.
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 boundary instead of inside.
Project shape
The codebase has two halves connected by CSV files:
- C# pipeline —
RacePredictor.Core (domain types + RacingPost/ parsers and downloader) and RaceDataDownloader (CLI verb handlers under Commands/). Tested in RacePredictor.Core.Tests and RaceDataDownloader.Tests.
- Python ML stage —
Data/*.py (notebook-derived scripts: FeatureAnalysis, HorseStatsBuilder, JockeyStatsBuilder, LinearRegressionPredictor). Read CSVs produced by the C# stage, write feature/prediction CSVs.
These are usually deepened separately. Cross-stage changes are coordinated through the CSV schema (e.g. Results_YYYYMM.csv, Race_Features.csv).
Process
1. Explore the codebase
Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
- Where does understanding one concept require bouncing between many small files? (e.g. a
*ParserShould test that pulls in five HtmlNode* helpers)
- Where are modules so shallow that the interface is nearly as complex as the implementation? (e.g. a one-method extension class used in one place)
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called? (e.g. a parser helper that's well-tested but is called wrongly inside the downloader)
- Where do tightly-coupled modules create integration risk in the seams between them? (e.g. CSV schema mismatches between the C# writer and the Python reader)
- Which parts of the codebase are untested, or hard to test? (Python
Data/*.py is the obvious gap; some Commands/ may be too.)
The friction you encounter IS the signal.
2. Present candidates
Present a numbered list of deepening opportunities. For each candidate, show:
- Cluster: Which modules/concepts are involved (e.g.
HtmlNodeFinder + RaceCardRunnerParser + RaceCardParser)
- Why they're coupled: Shared types, call patterns, co-ownership of a concept
- Dependency category: See REFERENCE.md for the four categories
- Test impact: What existing tests would be replaced by boundary tests
Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
3. User picks a candidate
4. Frame the problem space
Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
- The constraints any new interface would need to satisfy (e.g. must still expose
IAsyncEnumerable<string> for URL streaming, must keep IFileSystem-injectability)
- The dependencies it would need to rely on
- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
5. Design multiple interfaces
Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a radically different interface for the deepened module.
Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
- Agent 2: "Maximize flexibility — support many use cases and extension"
- Agent 3: "Optimize for the most common caller — make the default case trivial"
- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
Each sub-agent outputs:
- Interface signature (types, methods, params) — C#
interface declarations or Python ABCs as appropriate
- Usage example showing how callers use it (e.g. how
UpdateResultsCommandHandler would consume it)
- What complexity it hides internally
- Dependency strategy (how deps are handled — see REFERENCE.md)
- Trade-offs
Present designs sequentially, then compare them in prose.
After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
6. User picks an interface (or accepts recommendation)
7. Write issue file
Write the refactor RFC as a local markdown file in issues/ (numbered NNN-short-title.md, continuing from the highest existing number) using the template in REFERENCE.md. Do NOT ask the user to review before writing — just write it and share the path. Do NOT call gh issue create or any GitHub CLI command.
