From code-foundations
Guides deep design of modules, APIs, or classes: generate 2-3 radically different approaches, sketch, compare pros/cons, evaluate depth before implementing code.
npx claudepluginhub ryanthedev/code-foundationsThis skill uses the workspace's default tool permissions.
**Never implement your first design.** Generate 2-3 radically different approaches, compare them, then implement.
Designs module interfaces using parallel sub-agents to generate radically different options, compares on depth, simplicity, efficiency, and grills the synthesis. For new APIs, refactors, interface exploration.
Generates multiple radically different interface designs for modules or APIs using parallel sub-agents. Use when designing APIs, exploring options, comparing module shapes, or 'design it twice'.
Generates 3-4 radically different module or API contract designs in parallel under divergent constraints, presents sequentially with examples, and compares on depth, simplicity, ease-of-correct-use. For new interface shaping or 'design it twice'.
Share bugs, ideas, or general feedback.
Never implement your first design. Generate 2-3 radically different approaches, compare them, then implement.
BEFORE implementing any module:
1. DEFINE - What are you designing? (class, API, service)
2. GENERATE - 2-3 RADICALLY different approaches
3. SKETCH - Rough outline each (important methods only, no implementation)
4. COMPARE - List pros/cons, especially ease of use for callers
5. EVALUATE - Is there a clear winner or hybrid?
6. VERIFY - Does chosen design pass depth evaluation?
7. IMPLEMENT - Only then write the code
Time bound: Smaller modules: 1-2 hours. Larger modules: scale proportionally. This is design time, not implementation time.
If none attractive: Use identified problems to drive a new iteration of step 2.
| Metric | Deep (Good) | Shallow (Bad) |
|---|---|---|
| Interface size | Few methods | Many methods |
| Method reusability | Multiple use cases | Single use case |
| Hidden information | High | Low |
| Caller cognitive load | Low | High |
| Common case | Simple | Complex |
Exemplar: Unix file I/O - 5 methods hide hundreds of thousands of lines of implementation.
Ask these when designing interfaces:
| Question | Purpose | Red Flag Answer |
|---|---|---|
| "What is the simplest interface that covers all current needs?" | Minimize method count | "I need many methods" |
| "In how many situations will this method be used?" | Detect over-specialization | "Just this one situation" |
| "Is this easy to use for my current needs?" | Guard against over-generalization | "I need lots of wrapper code" |
When embedding functionality in a module:
Target: Somewhat general-purpose
| Aspect | Should Be |
|---|---|
| Functionality | Reflects current needs |
| Interface | Supports multiple uses |
| Specialization | Pushed up to callers OR down into variants |
Push specialization UP: Top-level code handles specific features; lower layers stay general.
Push specialization DOWN: Define general interface, implement with device-specific variants.
| Red Flag | Symptom | Fix |
|---|---|---|
| Shallow Module | Interface complexity rivals implementation | Combine with related functionality |
| Classitis | Many small classes with little functionality each | Consolidate related classes |
| Single-Use Method | Method designed for exactly one caller | Generalize to handle multiple cases |
| Information Leakage | Same knowledge in multiple modules | Consolidate in single module |
| Temporal Decomposition | Structure mirrors execution order | Structure by knowledge encapsulation |
| False Abstraction | Interface hides info caller actually needs | Expose necessary information |
| Granularity Mismatch | Caller must do work that belongs in module | Move logic into module |
Before finalizing your design choice, verify:
If user expresses impatience: Acknowledge it, but complete the process. Say: "I hear the urgency - this comparison takes 2 minutes and helps avoid rework."
Skip the normal workflow ONLY when ALL of these conditions are true:
When designing, produce:
## Design: [Component Name]
### Approaches Considered
1. [Approach A] - [1-2 sentence description]
2. [Approach B] - [1-2 sentence description]
3. [Approach C] - [1-2 sentence description] (if applicable)
### Comparison
| Criterion | A | B | C |
|-----------|---|---|---|
| Interface simplicity | | | |
| Information hiding | | | |
| Caller ease of use | | | |
| [Domain-specific criterion] | | | |
### Choice: [A/B/C/Hybrid]
Rationale: [Why this wins, what's sacrificed]
### Depth Check
- Interface methods: [count]
- Hidden details: [list]
- Common case complexity: [simple/moderate/complex]
| After | Next |
|---|---|
| Design chosen | cc-pseudocode-programming |