Check the width of comment lines

[onechat] / .agents / skills / go-code / SKILL.md

diff --git a/.agents/skills/go-code/SKILL.md b/.agents/skills/go-code/SKILL.md
index a9e705b7d1c53ecae9d952b35def3a5d4859dcf2..213a7d5aacfa004851b75794f38876f5c890b0b2 100644 (file)
--- a/.agents/skills/go-code/SKILL.md
+++ b/.agents/skills/go-code/SKILL.md
@@ -15,6 +15,15 @@ description: Go style rules. Use before you write or review Go code.
   methods in one file. Give a separate responsibility its own type.
 - When code in one file gets a user in another file for an unrelated
   purpose, move it to a file named for its function in the same change.
   methods in one file. Give a separate responsibility its own type.
 - When code in one file gets a user in another file for an unrelated
   purpose, move it to a file named for its function in the same change.

+- Start each package-level name that belongs to one feature or
+  integration with the name of that feature. Start the names of its
+  files with the same name. Keep a name generic only when more than one
+  feature uses it.
+- Write type names with a capital letter, so that a variable can have
+  the name of its type. Write all other package-level names in lower
+  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.
 - 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.


@@ -31,6 +40,15 @@ description: Go style rules. Use before you write or review Go code.
   Call `defer cancel()` immediately after you create the context.
 - Reuse `ctx` when a child context replaces its parent. Use a different
   name only when both contexts stay in use. Return `ctx.Err()` directly.
   Call `defer cancel()` immediately after you create the context.
 - Reuse `ctx` when a child context replaces its parent. Use a different
   name only when both contexts stay in use. Return `ctx.Err()` directly.

+- Derive each context from the context of the caller. When work must
+  finish even after the caller is cancelled, such as a final write, use
+  `context.WithoutCancel` of the caller's context. Use
+  `context.Background()` only where no caller context exists: in `run`,
+  and in methods that follow `io.Closer`.
+- Name a duration that limits one operation after that operation, and
+  end the name with `Timeout`, so that the name says what it limits
+  without its comment. Define it in the file that applies it, not in the
+  file of another type.

 
 ## Errors
 
 
 ## Errors
 


@@ -39,12 +57,31 @@ description: Go style rules. Use before you write or review Go code.
   different variable only to keep or join errors.
 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an
   error directly with a sentinel, because errors can be wrapped.
   different variable only to keep or join errors.
 - Use `errors.Is` and `errors.As` to examine errors. Do not compare an
   error directly with a sentinel, because errors can be wrapped.

+  `errorlint` checks comparisons and type assertions on errors.

 - When a function has more than one error path, wrap each returned error
   with the context of its operation. A function with one error path can
 - When a function has more than one error path, wrap each returned error
   with the context of its operation. A function with one error path can

-  return the error directly.
+  return the error directly. `wrapcheck` checks package and interface
+  calls, with the exceptions in `.golangci.yml`. Review local calls and
+  the number of error paths by hand.

 - When deferred cleanup can fail, use a named `err` result and join the
   cleanup error with `errors.Join`.
 
 - When deferred cleanup can fail, use a named `err` result and join the
   cleanup error with `errors.Join`.
 

+## Logs
+
+- Log with the `*slog.Logger` of the part (`daemonLogger`). The handler
+  formats the line; do not format values into the message.
+- Write the message as a short event in plain words, such as "receive
+  failed" or "subagent done". Do not explain what it means or what the
+  user must do.
+- Put names, IDs, counts, and durations in attributes, with short keys
+  (`name`, `id`, `after`, `retry`). Put the cause in `err`; the handler
+  writes it last.
+- Use info for normal events, warn for a failure that is retried or
+  loses nothing, and error for a failure that loses data or stops a
+  part.
+- Never log secrets, tokens, message text, or phone numbers. Redact IDs
+  as the existing code does.
+

 ## Style
 
 - Keep function signatures on one line. Write function bodies on more
 ## Style
 
 - Keep function signatures on one line. Write function bodies on more


@@ -60,7 +97,8 @@ description: Go style rules. Use before you write or review Go code.
 - 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
 - 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.
+  immediate use. `wsl_v5` and `nlreturn` check part of this rule. Review
+  the remaining logical blocks and immediate-use groups 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.
 - 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.


@@ -78,11 +116,15 @@ description: Go style rules. Use before you write or review Go code.
 
 - Add tests for meaningful behavior. Do not add tests that only repeat
   implementation details.
 
 - Add tests for meaningful behavior. Do not add tests that only repeat
   implementation details.

-- Use `testify/require` for assertions.
+- Use `testify/require` for assertions. `testifylint` checks the
+  assertion forms.

 - 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.
 - 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.

+- 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`.

 - Supply valid required dependencies in tests. Do not make a dependency
   optional only to make a test simpler.
 - Supply valid required dependencies in tests. Do not make a dependency
   optional only to make a test simpler.