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 ## Documentation
   9
  10 - `README.rst` is the entry point. It says what OneChat is, its status,
  11   and how to build, run, and check it. Keep it short.
  12 - Write the README for the user: what to set up, which commands to run,
  13   and what the agent does, in the user's words. A new feature adds at
  14   most a few lines to it.
  15 - Keep internals out of the README: internal files and their formats,
  16   locks, queues, recovery after a stop, limits, and edge cases. Put them
  17   in the Go doc comments of the code that owns them.
  18 - Do not add other documentation files or a `docs/` folder. Document
  19   commands and flags in the command help, and code contracts and design
  20   reasons in Go doc comments.
  21 - Use Markdown only for files that a tool requires by name, such as
  22   `AGENTS.md` and `SKILL.md`.
  23
  24 ## Lists
  25
  26 - Give each list item one paragraph only. Put a code block or a second
  27   paragraph after the list, because the formatters add an empty line
  28   between all items of a list that has one.
  29
  30 ## Comments
  31
  32 - A comment explains the declaration that it belongs to: the contract,
  33   invariants, and non-obvious reasons. Do not repeat what the code shows
  34   or describe unrelated caller behavior.
  35 - Update or remove a comment when its code changes.
  36 - Write prose comments as continuous paragraphs, with one space between
  37   words and sentences. Do not use semicolons in prose.
  38 - Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  39   by hand or with your own editor configuration.
  40 - Give `bin/reflow` the first and the last line of the paragraph only.
  41   Lists, examples, and directives in a comment keep their line breaks.
  42
  43 This example reflows the comment on lines 12 to 15:
  44
  45 ```sh
  46 bin/reflow main.go 12 15
  47 ```