// Use when reviewing code, assessing interfaces, during PR review, or evaluating 'is this too complex?' Triggers on: code review, design review, module complexity, interface assessment, PR review, structural analysis.
Use when designing modules, APIs, or classes before implementation.
Use when code is too complex, has scattered error handling, configuration explosion, or callers doing module work. Triggers on: too complex, simplify, scattered errors, configuration proliferation, verbose error handling
Use after implementing code. Triggers on: is it done, ready to commit, verify correctness, did I miss anything, pre-commit check.
Use when code has deep nesting (3+ levels), complex conditionals, loop design questions, high cyclomatic complexity (McCabe >10), or callback hell. Symptoms: arrow-shaped code, repeated conditions, confusing loop exits, lengthy if-else chains
Use when auditing defensive code, designing barricades, choosing assertion vs error handling, or deciding correctness vs robustness strategy. Triggers on: empty catch blocks, missing input validation, assertions with side effects, wrong exception abstraction level, garbage in garbage out mentality, deadline pressure to skip validation, trusted source rationalization.
Use when designing routines, stuck on where to start coding, caught in compile-debug loops, or code works but you don't understand why. Triggers on: starting a new coding task
| name | aposd-reviewing-module-design |
| description | Use when reviewing code, assessing interfaces, during PR review, or evaluating 'is this too complex?' Triggers on: code review, design review, module complexity, interface assessment, PR review, structural analysis. |
Run the checklist. The checklist exists because intuition misses structural problems.
Unknown unknowns are highest severity. If it's unclear what code/info is needed for changes, flag immediately.
Use this systematic checklist when reviewing code:
| Symptom | Question | If Yes |
|---|---|---|
| Change Amplification | Does a simple change require modifications in many places? | Flag dependency problem |
| Cognitive Load | Must developer know too much to work here? | Flag obscurity or leaky abstraction |
| Unknown Unknowns | Is it unclear what code/info is needed for changes? | Highest severity - flag immediately |
| Check | Deep (Good) | Shallow (Bad) |
|---|---|---|
| Interface vs implementation | Interface much simpler | Interface rivals implementation |
| Method count | Few, powerful methods | Many, limited methods |
| Hidden information | High | Low |
| Common case | Simple to use | Complex to use |
Red flag: If understanding the interface isn't much simpler than understanding the implementation, the module is shallow.
| Red Flag | Detection | Severity |
|---|---|---|
| Information Leakage | Same knowledge in multiple modules | High |
| Temporal Decomposition | Structure mirrors execution order rather than knowledge | Medium |
| Back-Door Leakage | Shared knowledge not visible in interfaces but both depend on it | High |
| Overexposure | Common use forces learning rare features | Medium |
| Red Flag | Detection | Severity |
|---|---|---|
| Pass-Through Method | Method only passes arguments to another with same API | High |
| Adjacent Similar Abstractions | Following operation through layers, abstractions don't change | High |
| Shallow Decorator | Large boilerplate, small functionality gain | Medium |
Test: Follow a single operation through layers. Does the abstraction change with each method call? If not, there's a layer problem.
| Red Flag | Detection | Severity |
|---|---|---|
| Conjoined Methods | Can't understand one method without another's implementation | High |
| Special-General Mixture | General mechanism contains use-case specific code | High |
| Code Repetition | Same code appears in multiple places | Medium |
| Shallow Split | Method split resulted in interface ≈ implementation | Medium |
| Red Flag | Source | One-Line Detection |
|---|---|---|
| Shallow Module | Ch4 | Interface as complex as implementation |
| Classitis | Ch4 | Many small classes, little functionality each |
| Information Leakage | Ch5 | Same knowledge in multiple modules |
| Temporal Decomposition | Ch5 | Structure follows execution order |
| Pass-Through Method | Ch7 | Method just delegates to another with same API |
| Conjoined Methods | Ch9 | Methods only understandable together |
| Special-General Mixture | Ch9 | General mechanism has use-case code |
| Code Repetition | Ch9 | Same code appears multiple places |
| Shallow Split | Ch9 | Method split resulted in interface ≈ implementation |
When evaluating whether code should be combined or separated:
1. Do pieces share information?
YES → Should probably be together
2. Would combining simplify the interface?
YES → Should probably be together
3. Is there repeated code?
YES → Extract shared method (if long snippet, simple signature)
4. Does module mix general-purpose with special-purpose?
YES → Should be separated
Key principle: Depth > Length. Never sacrifice depth for length.
| Situation | Correct Action |
|---|---|
| Long method with clean abstraction | Keep together |
| Short method requiring another's impl to understand | Combine them |
| Method split creating conjoined pair | Undo the split |
| Long method with extractable subtask | Extract subtask only |
Test for valid split: Can the pieces be understood independently AND reused separately?
When reporting findings, use:
## Design Review: [Component Name]
### Critical Issues (Must Address)
- [Red flag]: [Specific location] - [Why it's a problem]
### Moderate Issues (Should Address)
- [Red flag]: [Specific location] - [Why it's a problem]
### Observations (Consider)
- [Pattern noticed] - [Potential concern]
### Positive Patterns
- [What's working well]
Before reporting any red flag, validate:
Ask before concluding:
| Question | If Yes |
|---|---|
| Is there an existing pattern for this type of problem? | Compare approaches |
| Does this introduce a second way to do the same thing? | Flag unless justified |
| Would a maintainer be surprised by the difference? | Requires explicit documentation |
Balance: Evaluate patterns on merit, but don't create gratuitous inconsistency. The goal is maintainability, not conformance.
| Conflict | Resolution |
|---|---|
| Depth vs Cohesion | Prefer cohesion. A focused shallow module beats a bloated deep one. |
| Information Hiding vs Testability | Testing seams (injectable dependencies) are acceptable "leakage" |
| Simple Interface vs Configurability | Real systems need configuration; penalize only unnecessary complexity |
| Mistake | Reality |
|---|---|
| "It's long, so it's complex" | Length ≠ complexity. Depth matters more. |
| "Small classes are better" | Small classes are often shallow. Deep > small. |
| "More methods = better API" | Fewer powerful methods beat many limited ones. |
| "Separation is always good" | Subdivision has complexity costs. Sometimes combine. |
| "Code reuse requires extraction" | Only extract if snippet is long AND signature is simple. |
| "This is clearly good/bad" | Always run the systematic checklist. |
| "Standard pattern = automatically good" | Patterns can be misapplied. Require specific evidence. |
SYSTEMATIC REVIEW CHECKLIST:
1. SYMPTOMS - Change amplification? Cognitive load? Unknown unknowns?
2. DEPTH - Interface simpler than implementation?
3. HIDING - Same knowledge in multiple modules?
4. LAYERS - Pass-through methods? Abstraction changes per layer?
5. STRUCTURE - Conjoined methods? Special-general mixture?
BEFORE FLAGGING:
- Steel-man check: Could this be intentional?
- Validate: Can caller use without knowing implementation?
OUTPUT:
- Critical (must fix)
- Moderate (should fix)
- Observations (consider)
- Positive patterns
| After | Next |
|---|---|
| Issues found | Fix or flag for /code-foundations:plan |
| No issues | Done |