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 - Do not add other documentation files or a `docs/` folder. Document
  13   commands and flags in the command help, and code contracts and design
  14   reasons in Go doc comments.
  15 - Use Markdown only for files that a tool requires by name, such as
  16   `AGENTS.md` and `SKILL.md`.
  17
  18 ## Lists
  19
  20 - Give each list item one paragraph only. Put a code block or a second
  21   paragraph after the list, because the formatters add an empty line
  22   between all items of a list that has one.
  23
  24 ## Comments
  25
  26 - A comment explains the declaration that it belongs to: the contract,
  27   invariants, and non-obvious reasons. Do not repeat what the code shows
  28   or describe unrelated caller behavior.
  29 - Update or remove a comment when its code changes.
  30 - Write prose comments as continuous paragraphs, with one space between
  31   words and sentences. Do not use semicolons in prose.
  32 - Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  33   by hand or with your own editor configuration.
  34 - Give `bin/reflow` the first and the last line of the paragraph only.
  35   Lists, examples, and directives in a comment keep their line breaks.
  36
  37 This example reflows the comment on lines 12 to 15:
  38
  39 ```sh
  40 bin/reflow main.go 12 15
  41 ```