diegosouzapw Skill: aposd-simplifying-complexity
STOP - Error Reduction Hierarchy
Walk through each level of hierarchy for EACH error condition. The best way to deal with exceptions is to define errors out of existence.
Priority order: Define out → Mask → Aggregate → Crash (app-level only)
Do NOT present simplified code until the Transformation Checklist is complete.
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
| Situation | Wrong Approach | Right Approach |
|---|---|---|
| Uncertain what value to use | Export parameter | Compute automatically |
| Different contexts need different values | Export parameter | Use reasonable default, expose only for exceptions |
| Policy decision unclear | Let user decide | Make a decision and own it |
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:
| Priority | Technique | How It Works | Example |
|---|---|---|---|
| 1 | Define out | Change semantics so error is impossible | unset(x) = "ensure x doesn't exist" (not "delete existing x") |
| 2 | Mask | Handle at low level, hide from callers | TCP retransmits lost packets internally |
| 3 | Aggregate | Single handler for multiple exceptions | One catch block in dispatcher handles all NoSuchParameter |
| Special | Crash | Print diagnostic and abort (app-level only) | malloc failure in non-recoverable contexts |
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
| Exception Case | Why | What to Do Instead |
|---|---|---|
| Security-critical errors | Aggregating auth errors loses security-relevant distinctions | Keep distinct types for audit/logging |
| Retry-differentiated errors | Callers need different retry strategies per error type | Expose type info for retry decisions |
| Silent data loss risk | Define-out can mask user errors, complicate debugging | Fail fast for essential data errors |
| Library code | Callers should decide crash policy, not library | Expose errors; let app-level code crash |
Validation Gates
| Technique | Gate Question |
|---|---|
| Define out | Does anyone NEED to detect this error case? |
| Mask | Does the caller have ANY useful response to this error? |
| Aggregate | Do callers handle these errors identically? |
| Crash | Is this (a) application-level code, (b) truly unrecoverable, AND (c) crash acceptable? |
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):
| Question | If YES → | If NO → |
|---|---|---|
| Would this state occur in normal, correct operation? | Safe to define out | Fail fast |
| Can the caller proceed meaningfully with the "defined out" state? | Safe | Expose error |
| Does the user/system have another way to detect this condition if needed? | Safe | Consider exposing |
Obviousness Techniques
Three Ways to Make Code Obvious
| Technique | How | When to Use |
|---|---|---|
| Reduce information needed | Abstraction, eliminate special cases | Design-level changes |
| Leverage reader knowledge | Follow conventions, meet expectations | Incremental improvements |
| Present explicitly | Good names, strategic comments | When other techniques insufficient |
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
| Problem | Why Nonobvious | Fix |
|---|---|---|
| Generic containers (Pair, Tuple) | getKey() obscures meaning |
Define specific class with named fields |
| Event-driven handlers | Control flow hidden | Document invocation context |
| Type mismatches | List declared, ArrayList allocated |
Match declaration to allocation |
| Violated expectations | Code doesn't do what reader assumes | Document or refactor to meet expectations |
Mandatory Output: Show Your Work
Before presenting simplified code, output a technique analysis table:
| Error Condition | Technique | Gate Check | Reasoning |
|-----------------|-----------|------------|-----------|
| [each error] | [1-4] | [PASS/FAIL]| [why] |
This prevents claiming hierarchy application without evidence.
Transformation Checklist (Mandatory Gate)
Do NOT present simplified code until ALL boxes are checked:
- Walked through EACH level of hierarchy for EACH error condition
- Documented why earlier levels were rejected (if applicable)
- Verified validation gates passed for each technique applied
- 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
Anti-Rationalization Table
| Rationalization | Counter |
|---|---|
| "This is obvious, I don't need the hierarchy" | Stop. The hierarchy exists because intuition fails. Walk through each level explicitly. |
| "Define-out is over-engineering" | Stop. Define-out is the MOST valuable technique. Justify in writing why semantics cannot change. |
| "Python/language already handles this" | Stop. This IS masking (level 2). Document it explicitly as technique application, not skip. |
| "Creating a custom exception is overkill" | Stop. Count handlers before/after. If count drops, aggregation is worth it. |
| "I've seen this pattern before" | Stop. Pattern recognition ≠ systematic analysis. Walk hierarchy anyway. |
| "Callers might need to distinguish these errors" | Stop. Verify with evidence. Default is aggregate; distinguish only when proven necessary. |
| "The baseline was good enough" | Stop. "Good enough" is not the goal. The goal is minimal complexity. Check each level. |
| "The code is shorter, so it's simpler" | Stop. Complexity ≠ length. Verify: interfaces simpler? Callers do less? Errors consolidated? |
Principle Conflict Resolution
| Conflict | Resolution Heuristic |
|---|---|
| Define Out vs Fail Fast | Define out for incidental errors. Fail fast for essential errors. |
| Mask vs Explicit Handling | Mask when caller has no useful response. Expose when caller's response differs. |
| Aggregate vs Specific Messages | Aggregate the HANDLING, preserve specificity in the MESSAGE. |
| Pull Down vs Single Responsibility | Only pull down complexity RELATED to module's core purpose. |
| Obviousness vs Brevity | When define-out creates non-obvious behavior, add explanatory comment. |
| Simplify vs Performance | Prefer simplicity unless profiling proves performance-critical. |
Red Flags
| Red Flag | Symptom | Transformation |
|---|---|---|
| Scattered exceptions | Same error handled in many places | Aggregate to single handler |
| Configuration explosion | Many parameters exported | Compute automatically, provide defaults |
| Caller doing module's work | Logic outside that belongs inside | Pull complexity down |
| Over-defensive code | Checks for impossible conditions | Define errors out |
| Generic containers | Pair<X,Y> obscures meaning |
Create named structure |
| Comment-dependent understanding | Code unreadable without comments | Refactor for obviousness |
Quick Reference
SIMPLIFICATION PRIORITY ORDER:
1. Can I ELIMINATE this complexity entirely?
→ Redefine semantics, remove special cases
2. Can I CONSOLIDATE this complexity?
→ Pull down into one module, aggregate handlers
3. Can I HIDE this complexity?
→ Mask in implementation, use defaults
4. Can I CLARIFY this complexity?
→ Better names, strategic comments, meet conventions
Do NOT just move complexity around—reduce it.
Chain
| After | Next |
|---|---|
| Simplification done | Verify interface simplified |