new reference here

1 files changed, 98 insertions, 0 deletions

diff --git a/prompts/skills/go-best-practices/references/errcheck.md b/prompts/skills/go-best-practices/references/errcheck.md
new file mode 100644
index 0000000..d88044c
--- /dev/null
+++ b/prompts/skills/go-best-practices/references/errcheck.md
@@ -0,0 +1,98 @@
+# errcheck
+
+[errcheck](https://github.com/kisielk/errcheck) finds silently ignored errors
+in Go code. For every callable that is not in the excluded list, the returned
+error must either be assigned to a variable or explicitly discarded with `_`.
+This is a strong guardrail against the most common Go bug: dropping an error on
+the floor.
+
+errcheck does no further analysis on assigned errors (it will not complain if an
+assigned `err` is later overwritten without being checked). For that depth of
+analysis, also run [staticcheck](https://staticcheck.dev/).
+
+## Install
+
+```sh
+go install github.com/kisielk/errcheck@latest
+```
+
+errcheck requires Go 1.25 or newer. The binary is placed in `$GOPATH/bin`
+(default `~/go/bin`), so make sure that directory is on your `PATH`.
+
+## Use
+
+Check all packages beneath the current directory (the normal case for a repo):
+
+```sh
+errcheck ./...
+```
+
+Other invocations:
+
+```sh
+errcheck github.com/kisielk/errcheck/testdata   # a specific package path
+errcheck all                                     # everything in GOPATH/GOROOT
+```
+
+Useful flags:
+
+* `-blank` — also report errors assigned to the blank identifier (`_`), i.e.
+  catch *explicitly* discarded errors you may want to revisit.
+* `-asserts` — report ignored type-assertion results (`x, _ := i.(T)`).
+* `-ignoretests` — skip `_test.go` files.
+* `-ignoregenerated` — skip generated source.
+* `-tags '<tag1> <tag2>'` — space-separated build tags, like `go build`.
+* `-abspath` — print absolute paths to files with unchecked errors.
+* `-exclude <file>` — path to a file listing functions to exclude (see below).
+* `-excludeonly` — use only the supplied exclude file, disabling the built-in
+  standard-library exclude list.
+
+## Excluding functions
+
+Pass `-exclude errcheck_excludes.txt` with one signature per line. The format is
+`package.FunctionName` for functions and `(package.Receiver).MethodName` /
+`(*package.Receiver).MethodName` for value/pointer-receiver methods. Empty lines
+and `//` comments are ignored.
+
+```
+io.Copy(*bytes.Buffer)
+io.Copy(os.Stdout)
+os.ReadFile
+
+// Sometimes we don't care if a HTTP request fails.
+(*net/http.Client).Do
+```
+
+By default errcheck combines your list with an internal list of stdlib functions
+that have an error return but are documented never to fail. Use `-excludeonly` to
+disable that built-in list.
+
+## AI-assisted tools and guardrails
+
+Treat errcheck as a non-negotiable guardrail when an AI agent (or anyone) writes
+or modifies Go code in this project:
+
+* **Run it as part of verification**, alongside `go build ./...`, `go vet ./...`,
+  and `gofmt -l .`, before claiming a change is complete:
+
+  ```sh
+  errcheck ./...
+  ```
+
+* **Treat findings as defects, not noise.** Every reported call must either check
+  the error (wrap with `fmt.Errorf("...: %w", err)` per the error-handling
+  conventions) or be *intentionally* discarded with an explicit `_ =` and, where
+  it helps the reader, a short comment explaining why it is safe.
+
+* **Do not silence it by deleting the check.** Prefer fixing the code. If a
+  function genuinely never returns a meaningful error, add it to the project's
+  `errcheck_excludes.txt` so the exception is reviewed and documented, rather than
+  sprinkling blank assignments.
+
+* **Wire it into automation.** Add an `errcheck ./...` step to the Magefile
+  (e.g. a `Lint` target) and/or CI and a Git pre-commit hook so the guardrail
+  runs without relying on the agent remembering to invoke it.
+
+* **Honesty about what ran.** If errcheck is not installed or could not run, say
+  so explicitly instead of implying the code was checked (see "Environment
+  preflight and verification honesty" in the main skill).