errors-out.md

To have Claude Code apply the "Designing Errors out of Existence" philosophy to your Go codebase, you need a prompt that distinguishes between Critical Failures (which should remain errors) and State-based No-ops (which should be designed away).

The Audit & Refactor Prompt

"Audit the Go source code to identify functions that return an error but could be refactored to 'design the error out of existence' based on John Ousterhout’s philosophy. Please generate a report and suggest refactors for the following patterns:

1. Idempotent No-ops: Find functions where an error is returned for a state that already matches the desired outcome (e.g., Delete failing because a file is already gone, or Close failing on an already closed resource). If the post-condition is met, the function should succeed silently.
2. Empty-Set Safety: Find functions that return an error when a slice or map is empty. Refactor these to treat an empty input as a valid 'no-work-to-do' state rather than an error.
3. Internal Recovery: Identify functions where an error is passed to the caller, but the function could have made a sensible default decision or performed a safe retry internally.
4. Crash-Only Candidates: Identify 'Internal-only' initialization or setup functions where a failure is truly fatal to the CLI's execution. For these, suggest using panic or log.Fatal inside the function rather than forcing every caller in the stack to check an error that they cannot possibly recover from.

For each candidate, provide:

• The current signature and why the error is 'noise'.
• A proposed 'Error-free' signature.
• The 'Intent-Revealing' justification (e.g., 'Calling Close on a nil resource is a successful no-op, not a failure').

The goal is to reduce 'Error checking boilerplate' so that when a developer sees an if err != nil, they know it represents a truly exceptional and important event."

---

How to turn this into a Claude Code Skill

You can save this as a permanent command:

"Create a skill called eliminate-error-noise. When run, it should scan the repository for functions that return errors for idempotent operations or empty states. It should then propose refactors to 'define these errors out of existence,' making the API simpler for the caller by removing unnecessary error checks."

---

Key Areas to Target in Stave:

When Claude runs this, it should specifically look at these parts of your architecture:

1. internal/core/kernel/digest.go: If a hasher fails, can the CLI even continue? If not, MustDigest (which panics) is better than returning an error that 20 callers have to check.
2. internal/app/artifacts/clean.go: If you are cleaning a directory and it’s already empty, that’s a success. The os.IsNotExist check should be handled internally, and the function should return nil.
3. internal/core/evaluation/result.go: Functions that "Find" a finding. If it's not there, returning nil is often better than returning an ErrNotFound, as "not found" is a valid state in a search.
4. internal/doctor: If a diagnostic check fails, the check itself shouldn't return an error to the runner; it should simply record a "Fail" status in its report.

Why this is "Intent-Revealing":

In Go, we often get into the habit of adding , error to every signature "just in case." This creates "Error Fatigue." By designing errors out of existence, you ensure that errors are rare and meaningful. When the user sees an error in Stave, they should know it's a "Stop what you're doing" moment, not a "The file was already deleted" moment.