Explore the codebase like an AI, discover architectural friction points, uncover testability improvement opportunities, and propose module-deepening refactoring plans in the form of a GitHub Issue RFC.
Deep Modules(A Philosophy of Software Design by John Ousterhout) refers to modules with simple interfaces that hide a large amount of implementation detail. Deep modules are easier to test, easier for AI to navigate, and can be tested at the boundaries without going deep into the internals.
Process
1. Explore the codebase
Use the Agent tool (subagent_type=Explore) to browse the codebase naturally. Do not mechanically apply rules—explore organically and pay attention to where you encounter friction:
- Where does understanding one concept require jumping back and forth among many small files?
- Which modules are too shallow, with interfaces almost as complex as their implementations?
- Which pure functions were extracted only for testability, while the real bugs are hidden in how they are called?
- Which tightly coupled modules create integration risk at the seams between them?
- Which parts of the codebase lack tests, or are difficult to test?
The friction you encounter is itself the signal.
2. Present candidates
Present deepening opportunities as a numbered list. Each candidate must explain:
- Cluster: which modules/concepts are involved
- Reason for coupling: shared types, call patterns, concepts that belong together
- Dependency category: see REFERENCE.md for the four categories
- Testing impact: which existing tests will be replaced by boundary tests
Do not propose interface designs at this point. Ask the user: "Which one do you want to explore in depth?"
3. The user selects a candidate
4. Describe the problem space
Before launching subagents, write a problem-space description for the user for the selected candidate:
- Any constraints that a new interface needs to satisfy
- External dependencies that need to be depended on
- A rough illustrative code sketch to make the constraints more concrete—this is not a formal proposal, just something to make the constraints tangible
After presenting it to the user, immediately proceed to step 5. The user can let subagents work in parallel while reading and thinking about the problem.
5. Design multiple interface options
Use the Agent tool to launch 3 or more subagents in parallel. Each subagent must produce adistinctly differentinterface option for the deepened module.
Provide each subagent with an independent technical brief (file paths, coupling details, dependency categories, what needs to be hidden). This brief is independent of the user's description in step 4. Give each agent a different design constraint:
- Agent 1: "Minimize the interface—aim for at most 1-3 entry points"
- Agent 2: "Maximize flexibility—support multiple use cases and extensions"
- Agent 3: "Optimize for the most common callers—make the default scenario extremely simple"
- Agent 4 (if applicable): "Designing cross-boundary dependencies around the ports and adapters pattern"
Output from each sub-agent:
- Interface signatures (types, methods, parameters)
- Usage examples showing how callers use it
- What complexity is hidden internally
- Dependency strategy (how dependencies are handled — see REFERENCE.md)
- Trade-offs
Present each option in turn, then provide a comparative analysis in prose.
After the comparison, give your own recommendation: which option you think is best and why. If elements from different options combine well, propose a hybrid. Take a position — the user needs a strong judgment, not just a menu.
6. User selects an interface option (or accepts the recommendation)
7. Create a GitHub Issue
Use gh issue create to create the GitHub Issue for the refactoring RFC. Use the template in REFERENCE.md . Do not have the user review before creating — create it directly and share the link.