Skill: aposd-designing-deep-modules

STOP - Before Implementing

Never implement your first design. Generate 2-3 radically different approaches, compare them, then implement.

---

Design-It-Twice Workflow

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.

---

Depth Evaluation

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.

---

Three Questions Framework

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"

---

Information Hiding Checklist

When embedding functionality in a module:

• Data structures and algorithms stay internal
• Lower-level details (page sizes, buffer sizes) hidden
• Higher-level assumptions (most files are small) hidden
• No knowledge shared across module boundaries unnecessarily
• Common case requires no knowledge of internal details

---

Generality Sweet Spot

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 Flags

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

---

Anti-Rationalization Table

Tempting Shortcut	Why It Feels Right	Why It's Wrong
"I'm confident in my first idea"	Experience says it works	Complex problems defeat intuition; alternatives reveal hidden weaknesses
"I don't have time for multiple designs"	Deadline pressure	Design time << debugging time for wrong abstraction
"The alternatives would be worse"	Quick mental dismissal	Without sketching, you can't actually compare
"This is just a simple module"	Scope seems small	Small modules become core dependencies; getting them wrong cascades
"I'll refactor later if needed"	Deferred pain	Changing interfaces is expensive; callers multiply
"The user already knows what they want"	Seems respectful	They know the PROBLEM, not necessarily the best SOLUTION
"This is a standard pattern"	Feels like best practice	"Standard" often means "first thing I saw"; make it explicit
"I already know which is best"	Saves time	Then the comparison should be EASY, not skippable

---

Process Integrity Checks

Before finalizing your design choice, verify:

• I wrote out alternatives BEFORE evaluating them (not just "thought through" them)
• My comparison has at least one criterion where my preferred option loses
• If I chose a hybrid, I stated what I'm sacrificing from each parent approach
• Someone could reasonably disagree with my choice based on the same comparison

If user expresses impatience: Acknowledge it, but complete the process. Say: "I hear the urgency - this comparison takes 2 minutes and helps avoid rework."

---

Emergency Bypass Criteria

Skip the normal workflow ONLY when ALL of these conditions are true:

1. Production is down RIGHT NOW (not "might break soon")
2. Users are actively impacted, security breach in progress, OR data loss occurring
3. The fix is minimal (rollback or single-line change)
4. You commit to returning for proper implementation within 24 hours

Emergency does NOT mean:

• "Demo in 30 minutes" — That's planning failure
• "CEO is asking" — Authority pressure ≠ emergency
• "Team is blocked" — They can wait for you to think
• "We need this fast" — Speed pressure is when discipline matters MOST

---

Mandatory Output Format

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]

---

Chain

After	Next
Design chosen	cc-pseudocode-programming