Codebase error handling

Codebase Error Handling

Document the error handling, logging, and observability setup of a codebase. The output answers: "If something goes wrong in this code — at any layer — what's the right way to throw, propagate, log, report, and surface it to the user?"

Scope

This skill is narrow by design. It covers ONLY:

• Error type hierarchy (custom error classes, error codes, Result/Either types)
• How errors propagate (thrown vs returned, where caught, where rethrown)
• Logging library, format, and conventions
• Observability tooling (Sentry, Datadog, OpenTelemetry, PostHog error tracking)
• User-facing error surfaces (HTTP responses, toasts/SnackBars, dialogs, CLI exit codes)
• Recurring error-handling patterns

For everything else, point the user to a sister skill: codebase-overview for architecture, codebase-conventions for naming, codebase-testing-guide for tests, codebase-glossary for domain vocabulary.

What to Produce

A Markdown file with the structure below. Every section must include real examples from the actual codebase — real error class declarations, real throw/catch sites, real logger calls, real Sentry capture calls.

# {Project Name} — Error Handling

> Generated by codebase-error-handling on {YYYY-MM-DD}

## Error Type Hierarchy

{Custom error classes/types defined in the codebase. If there's a base class with subclasses, draw the hierarchy. If there are error codes or enums, list them.}

**Real example — base + subclass:**
\```{language}
{Real error class declarations from the codebase, copied verbatim}
\```

**Where defined:** `{path/to/errors/file}`

## Error Flow

{How errors propagate through layers. Are exceptions thrown and caught at the boundary? Are errors returned as values (Result, Either, tuple)? Where is the central catch point — middleware, handler wrapper, top-level try/catch? Are there any "error funnel" utilities that wrap arbitrary work?}

**Real example — throw site:**
\```{language}
{Real throw/raise statement showing the convention}
\```

**Real example — catch site:**
\```{language}
{Real catch block showing how errors are handled at the boundary}
\```

## Logging

{Library (winston / pino / loguru / structlog / standard logging / log package / dart logger), format (JSON / plaintext / structured), levels in use, log destinations, correlation IDs or request IDs.}

**Logger config / setup:** `{path}`

**Real example — typical log call:**
\```{language}
{Real logger usage from the codebase}
\```

## Observability

{Error monitoring (Sentry / Bugsnag / Rollbar / Honeybadger), APM (Datadog / New Relic / OpenTelemetry), front-end analytics with error tracking (PostHog / LogRocket). For each, show how it's wired up and where errors are reported.}

**Sentry / observability init:** `{path}`

**Real example — error capture:**
\```{language}
{Real capture call from the codebase}
\```

## User-Facing Errors

{How errors reach the user. For backend: HTTP status code conventions, error response shape, error code field. For frontend: toast/SnackBar usage, dialog patterns, inline error display. For CLI: exit codes, stderr formatting.}

**Real example — error response shape (backend):**
\```{language}
{Real example of a serialised error response from the codebase}
\```

**Real example — user-facing error UI (frontend):**
\```{language}
{Real toast/SnackBar/dialog code}
\```

## Recurring Patterns

For each pattern detected, include a description, where it shows up, and a real snippet.

### {Pattern 1 — e.g., "Hono typed error handler"}

{Description}

**Where it shows up:** `{file 1}`, `{file 2}`

**Snippet:**
\```{language}
{Real code}
\```

### {Pattern 2}
...

## Inconsistencies & Notes

{Any places where errors are swallowed (`catch (e) {}` with nothing inside), inconsistent logging levels for similar conditions, mixed error styles in the same module, TODO/FIXME notes near catch blocks. Also flag if observability is present in some layers but not others — that's a real gap.}

How to Scan

# Custom error classes (multi-language)
grep -rn "extends Error\|extends Exception\|class.*Error\|class.*Exception\|HttpError\|AppError\|CustomError" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" --include="*.dart" --include="*.java" --include="*.rs" 2>/dev/null | head -20

# Throw / raise sites
grep -rn "throw new\|^[[:space:]]*throw \|^[[:space:]]*raise " --include="*.ts" --include="*.tsx" --include="*.py" --include="*.dart" 2>/dev/null | head -20

# Result / Either / Option types (functional error handling)
grep -rn "Result<\|Either<\|Option<\|Ok(\|Err(\|.unwrap()\|.expect(" --include="*.ts" --include="*.rs" --include="*.go" 2>/dev/null | head -10

# Top-level catch / error boundary
grep -rn "ErrorBoundary\|onError\|errorHandler\|.catch(\|except [A-Z]\|recover()" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" --include="*.dart" 2>/dev/null | head -15

# Logging libraries
grep -rn "winston\|pino\|loguru\|structlog\|@logger\|console\.error\|console\.warn\|logger\.\|log\.[a-z]\|logging\.\|slog\." --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" --include="*.dart" 2>/dev/null | head -20

# Logger setup file (heuristic)
find . \( -name "logger.*" -o -name "logging.*" -o -name "log.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null | head -10

# Observability — Sentry
grep -rn "Sentry\.init\|Sentry\.captureException\|@sentry\|sentry_sdk\|sentry-flutter\|sentry-go" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" --include="*.dart" 2>/dev/null | head -15

# Observability — Datadog / OTEL / Bugsnag / Rollbar
grep -rn "datadog\|dd-trace\|opentelemetry\|@opentelemetry\|Bugsnag\|Rollbar\|Honeybadger" --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" 2>/dev/null | head -10

# Frontend user-facing error surfaces
grep -rn "toast\.error\|showSnackBar\|SnackBar(\|Alert(\|errorDialog\|notification\.error" --include="*.ts" --include="*.tsx" --include="*.dart" 2>/dev/null | head -15

# Backend error responses
grep -rn "res\.status(\|c\.json.*error\|HttpException\|abort(\|fastify\.error\|@app\.errorhandler" --include="*.ts" --include="*.tsx" --include="*.py" 2>/dev/null | head -15

# Empty / swallowed catches
grep -rn "catch ([a-z]*) {}" --include="*.ts" --include="*.tsx" 2>/dev/null | head -5
grep -rn "except.*:.*pass\|except.*:.*$" --include="*.py" 2>/dev/null | head -5

# CLI exit codes
grep -rn "sys\.exit\|process\.exit\|os\.Exit\|exit(" --include="*.ts" --include="*.py" --include="*.go" 2>/dev/null | head -10

When you find an interesting error class, throw site, or catch block, read the file to copy a real snippet — don't paraphrase. The literal code is the deliverable.

Where to Save

Check for an existing docs location:

• If docs/ exists, save as docs/error-handling.md
• If documentation/ exists, save as documentation/error-handling.md
• If .claude/ exists, save as .claude/error-handling.md
• Otherwise propose docs/error-handling.md and ask the user before creating

For monorepos with separate frontend/backend, ask the user whether to produce one combined doc or one per side — error handling often differs significantly across the boundary.

Principles

Real examples only. Every section must include at least one real, copy-pasteable example. Generic descriptions like "the project uses Sentry" without showing the actual init call and a capture site fail this skill's contract.

Cite locations. Include the file path with every example. The user should be able to open the file and see the convention in context.

Show the boundary. The most useful information in this doc is where errors get caught — the boundary between "errors propagate up" and "errors get handled." Find that boundary (middleware, route wrapper, error boundary, main try/catch) and document it explicitly.

Surface swallowed errors. catch (e) {} with empty body, except: pass without a comment, errors logged but not rethrown when they should be — flag these in "Inconsistencies & Notes." They're real bugs waiting to happen.

Distinguish layers. If frontend and backend handle errors differently (almost always true), structure the relevant sections to show both — don't force them into one description.

Don't drift in scope. Don't document architecture or testing. If observability ties into deployment (e.g., Sentry env detection from Firebase config), reference it briefly but don't expand on the deployment side.

After Producing

1. Save the file to the chosen location.
2. In chat, surface the 1–2 most surprising or non-obvious patterns — these are usually the ones that, when violated by a new contributor, cause production incidents.
3. If you found swallowed errors, missing observability in some layer, or inconsistent log levels for similar conditions, call those out — that's signal the team will care about.
4. Provide a path or link to the saved file.