error-handling.yaml

# Error Handling Code Review Guidelines
# Comprehensive rules for exception handling, error propagation, logging, user-facing errors, and graceful degradation

description: "Code review guidelines for error handling covering exceptions, error propagation, logging, and graceful degradation"
globs:
  - "**/*.ts"
  - "**/*.js"
  - "**/*.py"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/*.cs"
  - "**/*.rs"
  - "**/*.swift"
  - "**/*.kt"

rules:
  # ============================================================================
  # EXCEPTION HANDLING RULES
  # ============================================================================

  - name: use-specific-exceptions
    description: >
      Catch specific exception types, not generic Exception/Error. Specific
      catches allow appropriate handling per error type. Generic catches
      hide bugs and prevent proper recovery. Only catch what you can handle.
    severity: high

  - name: design-exception-hierarchy
    description: >
      Create meaningful exception hierarchies for your domain. Base exceptions
      for categories, specific exceptions for cases. Hierarchy enables catching
      at appropriate abstraction level. Document exception semantics.
    severity: medium

  - name: preserve-exception-context
    description: >
      When rethrowing or wrapping exceptions, preserve the original cause/stack
      trace. Lost context makes debugging impossible. Use language-specific
      chaining (cause in Java, __cause__ in Python, %w in Go).
    severity: high

  - name: avoid-empty-catch-blocks
    description: >
      Never have empty catch blocks. At minimum, log the error. Empty catches
      silently swallow errors, making debugging extremely difficult. If truly
      ignorable, document why explicitly.
    severity: critical

  - name: use-finally-for-cleanup
    description: >
      Use finally blocks or language equivalents (defer, using, with) to ensure
      resource cleanup regardless of exceptions. Uncleaned resources cause leaks
      and unpredictable behavior.
    severity: high

  # ============================================================================
  # ERROR PROPAGATION RULES
  # ============================================================================

  - name: define-error-boundaries
    description: >
      Define clear error boundaries in your architecture. Errors should be
      caught and handled at appropriate levels (controller, service, repository).
      Don't let low-level errors leak to users.
    severity: high

  - name: implement-fallback-strategies
    description: >
      Define fallback behavior when operations fail. Use default values, cached
      data, or degraded functionality. Fallbacks should be documented and tested.
      Some operations may have no fallback; that's also a decision.
    severity: medium

  - name: implement-retry-logic
    description: >
      Implement retry with exponential backoff for transient errors. Set max
      retry count and timeout. Only retry idempotent operations. Add jitter
      to prevent thundering herd. Log retry attempts.
    severity: medium

  - name: fail-fast-on-fatal-errors
    description: >
      Fail fast for unrecoverable errors (configuration errors, missing
      dependencies). Don't attempt recovery that will fail. Fast failure
      provides clearer diagnostics than limping along.
    severity: high

  - name: propagate-errors-consistently
    description: >
      Use consistent error propagation patterns throughout codebase. Return
      errors vs throwing exceptions should be consistent. Document error
      contracts for functions. Don't mix patterns arbitrarily.
    severity: medium

  # ============================================================================
  # LOGGING RULES
  # ============================================================================

  - name: include-error-context
    description: >
      Log errors with full context: operation being performed, relevant IDs,
      input values (sanitized), and state. Context enables debugging without
      reproduction. Don't log just "error occurred".
    severity: high

  - name: preserve-stack-traces
    description: >
      Log complete stack traces for exceptions. Stack traces show error origin
      and call path. Truncated or missing traces make debugging impossible.
      Configure logging frameworks to include traces.
    severity: high

  - name: use-correlation-ids
    description: >
      Include correlation/request IDs in error logs. Correlation IDs tie
      related logs across services and time. Essential for distributed system
      debugging. Propagate IDs through entire request lifecycle.
    severity: high

  - name: use-appropriate-log-levels
    description: >
      Use correct log levels: ERROR for failures requiring attention, WARN for
      potential issues, INFO for significant events, DEBUG for diagnostics.
      Don't log expected conditions as errors.
    severity: medium

  - name: avoid-logging-sensitive-data
    description: >
      Never log passwords, tokens, PII, or sensitive data in error logs.
      Sanitize error messages before logging. Audit logs for sensitive data
      leaks. Compliance requires data protection.
    severity: critical

  # ============================================================================
  # USER-FACING ERRORS RULES
  # ============================================================================

  - name: provide-user-friendly-messages
    description: >
      Error messages for users should be clear, actionable, and non-technical.
      Tell users what went wrong and what they can do. Never show stack traces
      or internal error codes to end users.
    severity: high

  - name: support-error-localization
    description: >
      Error messages should support localization. Use message keys and
      translation files, not hardcoded strings. Consider cultural differences
      in error communication.
    severity: medium

  - name: use-error-codes
    description: >
      Use structured error codes for programmatic handling. Codes like
      "USER_NOT_FOUND" or "INVALID_EMAIL_FORMAT" enable client-side handling.
      Document all error codes. Codes are more stable than messages.
    severity: medium

  - name: dont-expose-internal-details
    description: >
      Never expose internal implementation details in user-facing errors.
      Database errors, file paths, and server names are security risks.
      Log internally, show generic message externally.
    severity: critical

  # ============================================================================
  # GRACEFUL DEGRADATION RULES
  # ============================================================================

  - name: implement-circuit-breakers
    description: >
      Use circuit breakers to prevent cascading failures. Open circuit when
      failures exceed threshold, allow system to recover. Test circuit breaker
      behavior. Essential for resilient distributed systems.
    severity: high

  - name: set-appropriate-timeouts
    description: >
      Set timeouts for all external calls. No timeout means infinite wait.
      Timeouts should be appropriate for operation type. Use deadline
      propagation in distributed systems.
    severity: high

  - name: implement-graceful-fallbacks
    description: >
      When services fail, provide graceful fallbacks: cached data, default
      values, or reduced functionality. Fallbacks maintain partial service
      rather than complete failure. Test fallback behavior.
    severity: medium

  - name: design-for-partial-failure
    description: >
      Design systems to handle partial failures. If one service fails, others
      should continue. Use bulkheads to isolate failures. Test partial failure
      scenarios explicitly.
    severity: high

  - name: communicate-degraded-state
    description: >
      Communicate degraded state to users and monitoring. Show notifications
      when running on fallback. Alert operations team. Transparency about
      degradation enables appropriate response.
    severity: medium