ryanthedev/code-foundations/aposd-simplifying-complexity

Skill: aposd-simplifying-complexity

Error Reduction Hierarchy

The best way to deal with exceptions is to define errors out of existence.

Priority order: Define out → Mask → Aggregate → Crash (app-level only)

Pull Complexity Downward

Decision Procedure

Before adding complexity to an interface (new parameters, new exceptions, new caller responsibilities):

1. Is this complexity closely related to the module's existing functionality?
   NO  → Should it be pulled into a DIFFERENT module?
         YES → Identify correct module, pull there
         NO  → Leave in place (may be inherent to caller's domain)
   YES → Continue
 
2. Will pulling down simplify code elsewhere in the application?
   NO  → Do not pull down (no benefit)
   YES → Continue
 
3. Will pulling down simplify the module's interface?
   NO  → Do not pull down (risk of leakage)
   YES → Pull complexity down

All three conditions must be YES to pull down.

Critical Constraint: Pulling down UNRELATED complexity creates information leakage. If the complexity isn't intrinsic to the module's core abstraction, it doesn't belong there—find the right home or leave it with the caller.

Configuration Parameters

Configuration parameters represent incomplete solutions. Every parameter pushes complexity to every user/administrator. Prefer dynamic computation over static configuration.

Error Reduction Hierarchy

Apply in order of preference:

Note on "Crash": This is NOT level 4 of a hierarchy—it's a special case for truly unrecoverable errors in application code. Libraries should NEVER crash; they expose errors for callers to decide.

Error Reduction Decision Procedure

When facing an exception handling decision:
 
1. Can semantics be redefined to eliminate the error condition?
   YES → Define out of existence
   NO  → Continue
 
2. Can exception be handled at low level without exposing?
   YES → Mask
   NO  → Continue
 
3. Can multiple exceptions share the same handling?
   YES → Aggregate
   NO  → Continue
 
4. Is error rare, unrecoverable, and non-value-critical?
   YES → Just crash (app-level only)
   NO  → Must expose (exception information needed outside module)

When NOT to Apply Hierarchy

Validation Gates

Define-Out Appropriateness Test

Before defining an error out of existence, verify it's an incidental error (safe) not an essential error (must fail fast):

Obviousness Techniques

Three Ways to Make Code Obvious

Obviousness Test

If a code reviewer says your code is not obvious, it is not obvious—regardless of how clear it seems to you.

Common Obviousness Problems

Output Gate

Before presenting simplified code, produce a technique analysis table — this is the evidence that the hierarchy was applied:

| Error Condition | Technique | Gate Check | Reasoning |
|-----------------|-----------|------------|-----------|
| [each error]    | [1-4]     | [PASS/FAIL]| [why]     |

Proceed only when the following are true:

• Technique analysis table present for each error condition
• Complexity moved to fewer places (not just relocated)
• Interfaces are simpler than before
• Callers do less work than before
• Error handling is consolidated or eliminated
• Reader needs less context to understand

If a criterion legitimately cannot be satisfied, present the code with the failed criterion and reason stated.

Principle Conflict Resolution

Red Flags

CHECKER: run the ID'd checklist Read(${CLAUDE_SKILL_DIR}/checklists.md) against the code. CHECKER output: the ID'd checklist is the item set (the tables in this SKILL.md explain the items, they are not counted twice). Report each VIOLATION and WARNING as | Item | Status | Evidence | Location |; do not list passing or non-applicable items — close with one line N items checked, M pass, K n/a.