Share general review and documentation rules

[onechat] / .agents / skills / docs / SKILL.md

diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md
index 2f7f3dc97dc83ddfd2f37a4214fe8fc9dc6dfbe8..b95c3ba7839b166d80bceca8eb9feac4e513805b 100644 (file)
--- a/.agents/skills/docs/SKILL.md
+++ b/.agents/skills/docs/SKILL.md
@@ -5,6 +5,9 @@ description: Docs and comment rules. Use before you write any prose.
 
 # Documentation and comments
 
+Change documentation and comments in the same change as the behavior,
+interface, or constraint that they describe.
+
 ## Documentation
 
 - `README.rst` is the entry point. It says what OneChat is, its status,
@@ -17,9 +20,34 @@ description: Docs and comment rules. Use before you write any prose.
   in the Go doc comments of the code that owns them.
 - Do not add other documentation files or a `docs/` folder. Document
   commands and flags in the command help, and code contracts and design
-  reasons in Go doc comments.
+  reasons in Go doc comments. Keep help and Go comments consistent with
+  the implementation.
 - Use Markdown only for files that a tool requires by name, such as
   `AGENTS.md` and `SKILL.md`.
+- Follow
+  [Google's timeless documentation guide](https://developers.google.com/style/timeless-documentation).
+  Describe what the checked-in code does. Do not use labels that depend
+  on time, such as "new", "now", "currently", and "previously".
+- Follow
+  [Google's tense guide](https://developers.google.com/style/tense). Use
+  the present tense for general behavior. Use the future tense only when
+  the timing of an action requires it, not for planned features.
+- Keep previous designs, development history, roadmaps, and future work
+  in issues.
+- State exact support and limits instead of labels such as "prototype".
+  Keep implemented, tested, and unverified behavior apart.
+- Keep safety requirements and known limits explicit. For example, say
+  when fake-service tests do not verify compatibility with the live
+  service.
+- Keep compatibility and old-schema details when the code or the
+  migration tests require them. They describe an active contract, not
+  history.
+- Do not remove a warning or claim support only to remove historical
+  wording. Check the implementation and the tests before you change a
+  claim.
+- Compare claims, examples, paths, and links with the implementation and
+  the tests. Make sure that examples use supported interfaces and
+  contain no secrets.
 
 ## Lists
 
@@ -30,9 +58,13 @@ description: Docs and comment rules. Use before you write any prose.
 ## Comments
 
 - A comment explains the declaration that it belongs to: the contract,
-  invariants, and non-obvious reasons. Do not repeat what the code shows
-  or describe unrelated caller behavior.
-- Update or remove a comment when its code changes.
+  invariants, non-obvious reasons, and required compatibility behavior.
+  Do not repeat what the code shows or describe unrelated caller
+  behavior.
+- State input constraints, results, errors, and concurrency or resource
+  ownership rules when a caller needs them.
+- Keep a comment next to the code that it describes. Update or remove a
+  comment when its code changes.
 - Write prose comments as continuous paragraphs, with one space between
   words and sentences. Do not use semicolons in prose.
 - Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
@@ -45,3 +77,9 @@ This example reflows the comment on lines 12 to 15:
 ```sh
 bin/reflow main.go 12 15
 ```
+
+## Go comments
+
+- Follow [Go Doc Comments](https://go.dev/doc/comment). Write complete
+  sentences. Start a declaration comment with the name of the symbol.
+- Document each exported declaration and its contract.