X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/1a1e3835458e37b4b56897d6ff7804660798d60c..a50886435ab974bee6f96ddc0d92210549a01221:/.agents/skills/go-code/SKILL.md

diff --git a/.agents/skills/go-code/SKILL.md b/.agents/skills/go-code/SKILL.md
index 213a7d5..374c2e9 100644
--- a/.agents/skills/go-code/SKILL.md
+++ b/.agents/skills/go-code/SKILL.md
@@ -24,10 +24,15 @@ description: Go style rules. Use before you write or review Go code.
   case.
 - Write all the letters of an initialism in one case. `revive` checks
   common initialisms.
-- Put entry points first, then each struct's methods as a group, then
-  standalone utility functions. Do not put a utility function between
-  the methods of one type.
-- In each group, order functions by first use in the file.
+- Order declarations as imports, constants, variables, types,
+  constructors, methods, then standalone helpers. Types include structs,
+  interfaces, and aliases. Put all types before any constructor or
+  method, also when a file holds more than one type. The Tests section
+  gives the exception for files with tests.
+- Keep each type's methods in one group. Do not put a helper between
+  them. Order functions by first use within their declaration group, not
+  across groups. Entry points do not go before types or constructors
+  merely because they are entry points.
 
 ## Entry point and context
 
@@ -52,7 +57,12 @@ description: Go style rules. Use before you write or review Go code.
 
 ## Errors
 
-- Handle every returned error.
+- Handle every returned error, including an error assigned to `_`. Never
+  use a blank assignment to hide an unchecked error from a linter.
+  Handle meaningful errors. When the user approves an intentional
+  discard, call the operation with an explicit `// nolint: errcheck`
+  directive and a comment that gives the reason, not a blank assignment.
+  The `check` skill gives the approval rule.
 - Reuse an existing `err` for later operations in the same scope. Use a
   different variable only to keep or join errors.
 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an
@@ -94,11 +104,14 @@ description: Go style rules. Use before you write or review Go code.
   table-driven test. A small type of two fields that acts as one value,
   such as a key or a coordinate pair, can use a positional literal on
   one line.
-- Put an empty line between logical blocks, also after multiline
-  declarations, assignments, literals, and calls. Keep an operation with
-  its immediate error or result check. Keep a short declaration with its
-  immediate use. `wsl_v5` and `nlreturn` check part of this rule. Review
-  the remaining logical blocks and immediate-use groups by hand.
+- Put an empty line between logical blocks and after multiline
+  declarations, assignments, literals, and calls. The only exception
+  after a multiline construct is its immediate error check. Separate a
+  multiline literal from a following loop, even when the loop uses that
+  literal. Keep a single-line declaration with its immediate use, and an
+  operation with its immediate error check. This does not waive the
+  separator after a multiline construct. `wsl_v5` and `nlreturn` check
+  only part of this rule. Review the other boundaries by hand.
 - Use GNU-style command flags: two dashes for long flags, such as
   `--cwd`, and one dash only for one-letter flags, such as `-h`.
 - Prefer the Go standard library. Prefer Go over cgo.
@@ -121,8 +134,19 @@ description: Go style rules. Use before you write or review Go code.
 - Name a table-driven case slice `testCases` and its range variable
   `tc`. A subtest name describes the behavior, not a generic outcome or
   input.
-- In a test file, put constants immediately after the imports, then the
-  tests, then supporting types, methods, and helpers.
+- Each file with tests must have the name of its owning production file
+  with `_test` before `.go`: `memory_test.go` tests `memory.go`. Move
+  scenario and integration tests into their owner's test file. Do not
+  add an empty production file to make a test filename valid. Only
+  `_helper_test.go` files are exempt from this pairing rule.
+- In an ordinary `_test.go` file, order declarations as imports,
+  constants, variables, tests, supporting types, constructors, methods,
+  then helpers. This tests-first order is the exception to the
+  production order. Put all supporting types before their constructors
+  and methods.
+- A `_helper_test.go` file has no tests. Order its declarations as
+  imports, constants, variables, types, constructors, methods, then
+  helpers, as in a production file.
 - Keep a helper that only one test file uses in that file. Put a helper
   that more than one test file uses in a file without tests. Name that
   file for what it holds, and end the name with `_helper_test.go`.