# handling-failures

handling-failures — a skill that forces AI assistants to write honest error paths. Every failure either gets logged and rethrown, returns a typed error, or shifts the system into an explicit degraded mode.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 25500 installs · ★ 6 repo stars
- Author: riekelt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/handling-failures/SKILL.md
- Updated: 2026-09-11
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/handling-failures

## What it does

The core contract is simple: a failure path does one of three things. Log at WARN or ERROR and rethrow. Log and return a typed failure the caller must handle. Or log and enter a documented degraded mode with something observable marking the state. Bare catch-and-continue, returning an empty list or null, and `??` fallbacks that hide a failed primary are all forbidden.

Several rules follow from this. A missing required entry in a registry or config is a build or startup failure, never a quiet default. Retries of side-effecting operations have to be idempotent. Degraded modes need a named, operator-tunable threshold where degradation becomes abort. Observability ships with the fix — the log line, counter, and alert are part of the minimum.

This skill depends on the `principal-engineering` skill from the same repository. When you edit code that already swallows errors, the skill demands either fixing it in the same task or flagging it as owed debt with a note on what it hides. A new silent swallow in review is an automatic blocker.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill handling-failures -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/handling-failures/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/handling-failures/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill handling-failures -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/handling-failures/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill handling-failures -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/handling-failures/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/principal-engineer plugins/principal-engineer/skills/handling-failures
```

2. **Manually: put the files in place**
- File: `.github/skills/handling-failures/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill handling-failures -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/handling-failures
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/handling-failures/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill handling-failures -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/handling-failures/SKILL.md

## When to use it
- catch blocks that log nothing and keep running
- defaulting to null or an empty list on failure
- fallbacks that mask a broken primary source
- degraded modes with no documented stop threshold
- replaying non-idempotent side effects

## Example prompts
- This catch swallows an exception — rewrite it to log at ERROR and rethrow.
- Show me how to make this `??` fallback surface the primary source failure.
- Review this file for silent error swallows and propose fixes.

## Similar
- [error-handling-patterns](https://affpapa.org/en/nevibecode/skills/error-handling-patterns.md) — skill · 22957 installs
- [126-java-exception-handling](https://affpapa.org/en/nevibecode/skills/126-java-exception-handling.md) — skill · 307 installs
- [golang-error-handling](https://affpapa.org/en/nevibecode/skills/golang-error-handling.md) — skill · 46400 installs
- [error-handling](https://affpapa.org/en/nevibecode/skills/error-handling.md) — skill · 6600 installs
- [go-error-handling](https://affpapa.org/en/nevibecode/skills/go-error-handling.md) — skill · 1400 installs
- [0-error-handling](https://affpapa.org/en/nevibecode/rules/0-error-handling.md) — rule · ★ 571 repo stars

From the same set: [riekelt/principal-engineer](https://affpapa.org/en/nevibecode/by/riekelt/principal-engineer.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
