Skip to content
Skills Library
Programming · Review & audit

error-design

/error-design

Reviews error handling and exception design, applying the \"define errors out of existence\" principle. Use when reviewing error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Not for general caller-burden complexity (use pull-complexity-down); this skill is specifically for exception and error-condition strategy.

Licence
MIT
Last repository change
07.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Reviews error handling and exception design, applying the \"define errors out of existence\" principle. Use when reviewing error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Not for general caller-burden complexity (use pull-complexity-down); this skill is specifically for exception and error-condition strategy.

Triggers from the description

define errors out of existence\

Arguments

/error-design [file or module path]
Original author description

Reviews error handling and exception design, applying the \"define errors out of existence\" principle. Use when reviewing error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Not for general caller-burden complexity (use pull-complexity-down); this skill is specifically for exception and error-condition strategy.

How it works

  1. The "Too Many Exceptions" Anti-Pattern
  2. When to Apply
  3. Core Principles
  4. Review Process
Original SKILL.md headings · 99 lines, 890 words
SKILL.md preview
---
name: error-design
description: "Reviews error handling and exception design, applying the \"define errors out of existence\" principle. Use when reviewing error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Not for general caller-burden complexity (use pull-complexity-down); this skill is specifically for exception and error-condition strategy."
argument-hint: "[file or module path]"
allowed-tools: Read, Grep
---

# Error Design Review Lens

When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.

**Each exception a module throws is an interface element.** The best way to deal with exceptions is to not have them.

## The "Too Many Exceptions" Anti-Pattern

Programmers are often taught that "the more errors detected, the better," but this produces an over-defensive style that throws exceptions for anything suspicious. Throwing is easy. Handling is hard. Each exception type in a module's interface is one more thing callers must understand and prepare for, making the class shallower than it needs to be. Exception handlers are rarely exercised in practice, which means bugs in them accumulate silently. When a handler is finally needed, it may not work.

## When to Apply

- Reviewing error handling code or exception hierarchies
- When a function has many error cases or throws many exception types
- When callers are burdened with handling errors that rarely occur
- When error handling code is longer than the happy path

## Core Principles

### The Decision Tree

_The four techniques below have no canonical ordering. This tree sequences them by preference for practical use._

For every error condition:

#### 1. Can the error be defined out of existence?

Change the interface so the condition isn't an error. If yes: do this. Always the best option.

#### 2. Can the error be masked?

Handle internally without propagating. If yes: mask if handling is safe and complete.

#### 3. Can the error be aggregated?

Replace many specific exceptions with one general mechanism. If yes: aggregate to reduce interface surface.

#### 4. Must the caller handle it?

Propagate only if the caller genuinely must decide. If the caller can't do anything meaningful: crash.

### Define Errors Out of Existence

**Error conditions follow from how an operation is specified. Change the specification, and the error disappears.**

The general move: instead of "do X" (fails if preconditions aren't met), write "ensure state S" (trivially satisfied if state already holds).

- **Unset variable?** "Delete this variable" (fails if absent) → "ensure this variable no longer exists" (always succeeds)
- **File not found on delete?** Unix `unlink` doesn't "delete a file." It removes a directory entry. Returns success even if processes have the file open.
- **Substring not found?** Python slicing clamps out-of-range indices (no exception, no defensive code). Java's `substring` throws `IndexOutOfBoundsException`, forcing bounds-clamping around a one-line call.

Defining errors out of existence is like a spice: a small amount improves the result but too much ruins the dish. The technique only works when the exception information is genuinely not needed outside the module. A networking module that masked all network exceptions left callers with no way to detect lost messages or failed peers. Those errors needed to be exposed because callers depended on them to build reliable applications.

### Exception Masking

Handle internally without exposing to callers. Valid when:

- The module can recover completely
- Recovery doesn't lose important information
- The masking behavior is part of the module's specification

TCP masks packet loss this way. Before masking, ask whether a developer debugging the system would want to know it happened. If yes, log it. If the loss is irreversible and important, don't mask. Propagate.

### Exception Aggregation

Replace many specific exceptions with fewer general ones handled in one place. Masking absorbs errors low and aggregation catches errors high. Together they produce an hourglass where middle layers have no exception handling at all.

#### Web Server Pattern

Let all `NoSuchParameter` exceptions propagate to the top-level dispatcher where a single handler generates the error response. New handlers automatically work with the system. The same applies to any request-processing loop: catch in one place near the top, abort the current request, clean up and continue.

### Aggregation Through Promotion

Rather than building separate recovery for each failure type, promote smaller failures into a single crash-recovery mechanism. Fewer code paths, more frequently exercised (which surfaces bugs in recovery sooner). Trade-off: promotion increases recovery cost per incident, so it only makes sense when the promoted errors are rare.

### Just Crash

When an error is difficult or impossible to handle and occurs infrequently, the simplest response is to print diagnostic information and abort. Out-of-memory errors fit this pattern because there's not much an application can do and the handler itself may need to allocate memory. The same principle applies anywhere: wrap the operation so it aborts on failure, eliminating exception handling at every call site.

#### Appropriate When

The error is infrequent, recovery is impractical, and the caller can't do anything meaningful.

#### Not Appropriate When

The system's value depends on handling that failure (e.g., a replicated storage system must handle I/O errors, not crash on them).

## Review Process

1. **Inventory exceptions**: List every error case, exception throw, and error return.
2. **Apply the decision tree**: Can each one be defined out? Masked? Aggregated?
3. **Check depth impact**: How many exception types are in the module's interface?
4. **Audit catch blocks**: Are callers doing meaningful work, or just logging and re-throwing?
5. **Evaluate safety**: For any proposed masking, verify nothing important is lost.
6. **Recommend simplification**: Propose specific reductions in error surface.

Red flag signals for error design are cataloged in **red-flags** (Catch-and-Ignore, Overexposure, Shallow Module).

Versions

The database has no other skills named error-design.

Database snapshot: 13.11.2026 · package version 18a588426a31 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100php-error-handling
    Implement modern PHP error and exception handling patterns. Use when implementing exception hierarchies, error handlers, or custom exceptions in PHP.
  • 90pull-complexity-down
    Checks whether complexity is pushed to callers or absorbed by implementations — the direction complexity flows. Use when callers must do significant setup, handle errors the module could resolve, or configure things they don't understand. Not for module depth (use deep-modules),…
  • 98error-handling-patterns
    Design error handling strategies for TypeScript and Python applications — exception hierarchies, Result/Either types, retry patterns, error boundaries, and structured error logging. Use when designing error handling architecture, choosing between exceptions and Result types,…
  • 95software-design-philosophy
    Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design." Use this skill during: code reviews, architecture discussions, API design, module decomposition decisions, refactoring guidance, complexity analysis, naming and commenting…
  • 100python-error-handling
    Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs.
  • 100error-contract
    Standardized error response handling between frontend and backend. Covers error structure, status codes, and consistent error handling. USE WHEN: user asks about "error handling", "API errors", "error response format", "status codes", "error messages", "validation errors" DO NOT…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.