From: Anderson A. Giacomolli Date: Tue, 10 Nov 2026 14:39:58 +0000 (-0300) Subject: Keep the README for the user X-Git-Url: http://git.giacomolli.uk/onechat/commitdiff_plain/277a37a79b51910074a29ca6d70fae75c73619b7 Keep the README for the user The docs skill says that the README is for the user and that a feature adds at most a few lines to it, with internal files, locks, queues, recovery, and limits in Go doc comments. Short alone was not enough: each worker documented its feature in full, and the README grew to 700 lines. --- diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.md index b802f77..2f7f3dc 100644 --- a/.agents/skills/docs/SKILL.md +++ b/.agents/skills/docs/SKILL.md @@ -9,6 +9,12 @@ description: Docs and comment rules. Use before you write any prose. - `README.rst` is the entry point. It says what OneChat is, its status, and how to build, run, and check it. Keep it short. +- Write the README for the user: what to set up, which commands to run, + and what the agent does, in the user's words. A new feature adds at + most a few lines to it. +- Keep internals out of the README: internal files and their formats, + locks, queues, recovery after a stop, limits, and edge cases. Put them + 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.