agentleFS
Sign inStart free
MovGP0MovGP0/Skills/m06-error-handling/SKILL.md

m06-error-handling

Skill1 starsChanged 4 months agoMITView on GitHub

CRITICAL: Use for error handling. Triggers: Result, Option, Error, ?, unwrap, expect, panic, anyhow, thiserror, when to panic vs return Result, custom error, error propagation, 错误处理, Result 用法, 什么时候用 panic

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before choosing error handling strategy:

    line 15
  2. Distinctive:

    Before handling an error:

    line 35
  3. Distinctive:

    Call chain → anyhow::Context

    line 51
  4. Distinctive:

    When error strategy is unclear:

    line 58

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Error Handling

Layer 1: Language Mechanics

Core Question

Is this failure expected or a bug?

Before choosing error handling strategy:

  • Can this fail in normal operation?
  • Who should handle this failure?
  • What context does the caller need?

Error → Design Question

PatternDon't Just SayAsk Instead
unwrap panics"Use ?"Is None/Err actually possible here?
Type mismatch on ?"Use anyhow"Are error types designed correctly?
Lost error context"Add .context()"What does the caller need to know?
Too many error variants"Use Box<dyn Error>"Is error granularity right?

Thinking Prompt

Before handling an error:

  1. What kind of failure is this?
    • Expected → Result<T, E>
    • Absence normal → Option<T>
    • Bug/invariant → panic!
    • Unrecoverable → panic!
  2. Who handles this?
    • Caller → propagate with ?
    • Current function → match/if-let
    • User → friendly error message
    • Programmer → panic with message
  3. What context is needed?
    • Type of error → thiserror variants
    • Call chain → anyhow::Context
    • Debug info → anyhow or tracing

Trace Up ↑

When error strategy is unclear:

"Should I return Result or Option?"
    ↑ Ask: Is absence/failure normal or exceptional?
    ↑ Check: m09-domain (what does domain say?)
    ↑ Check: domain-* (error handling requirements)
SituationTrace ToQuestion
Too many unwrapsm09-domainIs the data model right?
Error context designm13-domain-errorWhat recovery is needed?
Library vs app errorsm11-ecosystemWho are the consumers?

Trace Down ↓

From design to implementation:

"Expected failure, library code"
    ↓ Use: thiserror for typed errors

"Expected failure, application code"
    ↓ Use: anyhow for ergonomic errors

"Absence is normal (find, get, lookup)"
    ↓ Use: Option<T>

"Bug or invariant violation"
    ↓ Use: panic!, assert!, unreachable!

"Need to propagate with context"
    ↓ Use: .context("what was happening")

Quick Reference

PatternWhenExample
Result<T, E>Recoverable errorfn read() -> Result<String, io::Error>
Option<T>Absence is normalfn find() -> Option<&Item>
?Propagate errorlet data = file.read()?;
unwrap()Dev/test onlyconfig.get("key").unwrap()
expect()Invariant holdsenv.get("HOME").expect("HOME set")
panic!Unrecoverablepanic!("critical failure")

Library vs Application

ContextError CrateWhy
LibrarythiserrorTyped errors for consumers
ApplicationanyhowErgonomic error handling
MixedBoththiserror at boundaries, anyhow internally

Decision Flowchart

Is failure expected?
├─ Yes → Is absence the only "failure"?
│        ├─ Yes → Option<T>
│        └─ No → Result<T, E>
│                 ├─ Library → thiserror
│                 └─ Application → anyhow
└─ No → Is it a bug?
        ├─ Yes → panic!, assert!
        └─ No → Consider if really unrecoverable

Use ? → Need context?
├─ Yes → .context("message")
└─ No → Plain ?

Common Errors

ErrorCauseFix
unwrap() panicUnhandled None/ErrUse ? or match
Type mismatchDifferent error typesUse anyhow or From
Lost context? without contextAdd .context()
cannot use ?Missing Result returnReturn Result<(), E>

Anti-Patterns

Anti-PatternWhy BadBetter
.unwrap() everywherePanics in production.expect("reason") or ?
Ignore errors silentlyBugs hiddenHandle or propagate
panic! for expected errorsBad UX, no recoveryResult
Box<dyn Error> everywhereLost type infothiserror

Related Skills

WhenSee
Domain error strategym13-domain-error
Crate boundariesm11-ecosystem
Type-safe errorsm05-type-driven
Mental modelsm14-mental-model

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free