improve-codebase-architecture

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

This is a .NET solution. Orient yourself before diving in:

• Identify the projects in the solution (*.sln/*.slnx) and their roles — domain/core libraries, application/entry-point projects (CLI command handlers, API endpoints, hosted services), and their paired test projects.
• Note the public contracts that connect layers (DTOs, records, serialized output formats) — these seams are where coupling and integration risk concentrate.

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 test that pulls in five tiny helper types to set up one behavior)
• Where are modules so shallow that the interface is nearly as complex as the implementation? (e.g. a one-method extension class used in a single place)
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called? (e.g. a well-tested helper that is invoked incorrectly by its caller)
• Where do tightly-coupled modules create integration risk in the seams between them? (e.g. a contract/schema mismatch between a producer and a consumer)
• Which parts of the codebase are untested, or hard to test?

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. NodeFinder + ItemParser + DocumentParser)
• 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<T> for 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:

1. Interface signature (types, methods, params) — C# interface or abstract class declarations
2. Usage example showing how callers use it (e.g. how a command handler would consume it)
3. What complexity it hides internally
4. Dependency strategy (how deps are handled — see REFERENCE.md)
5. 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.