checkpoint

Author: mikeschinkel

.squire/config.json

@@ -0,0 +1,34 @@
+{
+  "modules": {
+    "./examples/layered_errors": {
+      "name": "layered_errors",
+      "role": [
+        "lib"
+      ]
+    },
+    "./": {
+      "name": "go-doterr",
+      "role": [
+        "lib"
+      ]
+    },
+    "./test": {
+      "name": "test",
+      "role": [
+        "test"
+      ]
+    },
+    "./examples/basic_usage": {
+      "name": "basic_usage",
+      "role": [
+        "lib"
+      ]
+    },
+    "./examples/combined_errors": {
+      "name": "combined_errors",
+      "role": [
+        "lib"
+      ]
+    }
+  }
+}

README.md

@@ -230,6 +230,33 @@ if errors.Is(err, ErrDriver) {
 
 Why provide **two (2)** sentinels? It can often be useful to provide both a general purpose error — e.g. `ErrNotFound` — and a more-specific error — e.g. `ErrNoWidgetMatchedSearchTerm` — when characterizing errors.
 
+## Parameter types for NewErr()
+
+`NewErr(parts ...any)` accepts a variadic parameter, but **not all types are valid**:
+
+| Valid | Type | Position | Example |
+|-------|------|----------|---------|
+| ✅ | Sentinel error | First 1-2 positions | `ErrRepo`, `ErrNotFound` |
+| ✅ | Metadata key (string) | Followed by value | `"table"` |
+| ✅ | Metadata value (any) | After key | `"users"`, `42`, `obj` |
+| ✅ | Cause error | Last position only | `err` |
+| ❌ | Descriptive string | Any | `"failed to connect"` |
+| ❌ | fmt.Sprintf result | Any | `fmt.Sprintf("error: %s", msg)` |
+
+**Anti-pattern to avoid:**
+
+```go
+// ❌ WRONG - descriptive strings are not sentinels
+return NewErr(ErrCmd, "failed to resolve config directory", err)
+return NewErr(ErrCmd, fmt.Sprintf("no branch found (tried: %s)", list))
+
+// ✅ CORRECT - use sentinels + metadata
+return NewErr(ErrCmd, ErrResolvingConfigDir, err)
+return NewErr(ErrCmd, ErrNoBranchFound, "tried", list)
+```
+
+Descriptive strings bypass `errors.Is()` and cannot be matched programmatically. If you need to describe a failure condition, create a sentinel error for it.
+
 ## Layered composition example
 
 Each function layer defines **its own sentinel** and passes the error from the inner function as the trailing cause.