Skill: aposd-designing-deep-modules

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

Exemplar: Unix file I/​O - 5 methods hide hundreds of thousands of lines of implementation.

---

Three Questions Framework

Ask these when designing interfaces:

---

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

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

---

Anti-Rationalization Table

---

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