git.giacomolli.uk - onechat/blob - .agents/skills/docs/SKILL.md

   1 ---
   2 name: docs
   3 description: Docs and comment rules. Use before you write any prose.
   4 ---
   5
   6 # Documentation and comments
   7
   8 Change documentation and comments in the same change as the behavior,
   9 interface, or constraint that they describe.
  10
  11 ## Documentation
  12
  13 - `README.rst` is the entry point. It says what OneChat is, its status,
  14   and how to build, run, and check it. Keep it short.
  15 - Write the README for the user: what to set up, which commands to run,
  16   and what the agent does, in the user's words. A new feature adds at
  17   most a few lines to it.
  18 - Keep internals out of the README: internal files and their formats,
  19   locks, queues, recovery after a stop, limits, and edge cases. Put them
  20   in the Go doc comments of the code that owns them.
  21 - Do not add other documentation files or a `docs/` folder. Document
  22   commands and flags in the command help, and code contracts and design
  23   reasons in Go doc comments. Keep help and Go comments consistent with
  24   the implementation.
  25 - Use Markdown only for files that a tool requires by name, such as
  26   `AGENTS.md` and `SKILL.md`.
  27 - Follow
  28   [Google's timeless documentation guide](https://developers.google.com/style/timeless-documentation).
  29   Describe what the checked-in code does. Do not use labels that depend
  30   on time, such as "new", "now", "currently", and "previously".
  31 - Follow
  32   [Google's tense guide](https://developers.google.com/style/tense). Use
  33   the present tense for general behavior. Use the future tense only when
  34   the timing of an action requires it, not for planned features.
  35 - Keep previous designs, development history, roadmaps, and future work
  36   in issues.
  37 - State exact support and limits instead of labels such as "prototype".
  38   Keep implemented, tested, and unverified behavior apart.
  39 - Keep safety requirements and known limits explicit. For example, say
  40   when fake-service tests do not verify compatibility with the live
  41   service.
  42 - Keep compatibility and old-schema details when the code or the
  43   migration tests require them. They describe an active contract, not
  44   history.
  45 - Do not remove a warning or claim support only to remove historical
  46   wording. Check the implementation and the tests before you change a
  47   claim.
  48 - Compare claims, examples, paths, and links with the implementation and
  49   the tests. Make sure that examples use supported interfaces and
  50   contain no secrets.
  51
  52 ## Lists
  53
  54 - Give each list item one paragraph only. Put a code block or a second
  55   paragraph after the list, because the formatters add an empty line
  56   between all items of a list that has one.
  57
  58 ## Comments
  59
  60 - A comment explains the declaration that it belongs to: the contract,
  61   invariants, non-obvious reasons, and required compatibility behavior.
  62   Do not repeat what the code shows or describe unrelated caller
  63   behavior.
  64 - State input constraints, results, errors, and concurrency or resource
  65   ownership rules when a caller needs them.
  66 - Keep a comment next to the code that it describes. Update or remove a
  67   comment when its code changes.
  68 - Write prose comments as continuous paragraphs, with one space between
  69   words and sentences. Do not use semicolons in prose.
  70 - Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  71   by hand or with your own editor configuration.
  72 - Give `bin/reflow` the first and the last line of the paragraph only.
  73   Lists, examples, and directives in a comment keep their line breaks.
  74
  75 This example reflows the comment on lines 12 to 15:
  76
  77 ```sh
  78 bin/reflow main.go 12 15
  79 ```
  80
  81 ## Go comments
  82
  83 - Follow [Go Doc Comments](https://go.dev/doc/comment). Write complete
  84   sentences. Start a declaration comment with the name of the symbol.
  85 - Document each exported declaration and its contract.