error-design

Inventory and simplify exception hierarchies and error returns during code reviews.

11|Updated Feb 25, 2026

Search Tags:#code review #error handling #api design #recovery strategy #exception design #module complexity

Ready to run

npx skills add https://github.com/codybrom/clairvoyance --skill error-design

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: error-design
Source: https://github.com/codybrom/clairvoyance/tree/main/skills/error-design
Command: npx skills add https://github.com/codybrom/clairvoyance --skill error-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers reduce unnecessary exception complexity and prevent error handling from becoming a burdensome part of a module's interface.

Core Features & Use Cases

Exception Inventory: Identify error cases, thrown exceptions, error returns, and exception types exposed by a module.
Error Simplification: Evaluate whether errors can be defined out of existence, masked safely, aggregated, or promoted to a top-level recovery mechanism.
Interface Review: Assess how exception handling affects module depth, caller responsibilities, recovery behavior, and maintainability.
Use Case: Apply this Skill during a code review when callers handle numerous exceptions, catch blocks only log and rethrow, or error-handling code is longer than the happy path.

Quick Start

Ask the error-design skill to review the error handling and exception surface of the specified file or module.

Frequently Asked Questions about error-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I simplify error handling and reduce exception burden in my module?▼

To simplify error handling, inventory all exceptions and error returns, then evaluate whether each can be defined out of existence, masked safely, aggregated, or promoted to centralized recovery to reduce caller burden.

When should I review my exception design and error recovery strategy?▼

Review exception design when callers handle numerous exceptions, catch blocks only log and rethrow, or error-handling code exceeds the length of the happy path, indicating excessive module complexity and recovery burden.

What is the best way to evaluate if an API's exception hierarchy is too complex?▼

The best way to evaluate API exception complexity is assessing how exception handling affects module depth, caller responsibilities, and recovery behavior to determine if failure cases can be safely masked or aggregated.

Can I define module errors out of existence during a code review?▼

Yes, during a code review you can define errors out of existence by inventorying thrown exceptions and error returns, then evaluating whether each failure case can be safely masked, aggregated, or allowed to crash.

Why does my error handling code require more logic than the main execution path?▼

Error handling code exceeds the main path when a module exposes excessive failure cases and exception types to callers, requiring simplification through aggregation, safe masking, or centralized recovery mechanisms.

Does this approach work for modules with deeply nested exception hierarchies?▼

Yes, this approach works for nested exception hierarchies by assessing how exception handling affects module depth and caller responsibilities, promoting top-level recovery to reduce exposed interface burden.