From 612ea747203043ddca4a5c8436b4fb4543b0811a Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Tue, 28 Jul 2026 19:43:32 +0200 Subject: [PATCH] docs(agents): add positive-phrasing principle to documentation guide Record that docs state what the software does and reserve "does not" statements for behavior that contradicts the most obvious expectation. --- .agents/skills/documentation-guide/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.agents/skills/documentation-guide/SKILL.md b/.agents/skills/documentation-guide/SKILL.md index 03bcb75..a62f4c0 100644 --- a/.agents/skills/documentation-guide/SKILL.md +++ b/.agents/skills/documentation-guide/SKILL.md @@ -81,6 +81,7 @@ If the content needs multiple sentences of caveats, explains how an internal mec ## Writing principles - Lead with the user outcome, then the command or action needed. +- State what the software does rather than listing what it does not do; reserve "does not" statements for the rare case where behavior genuinely contradicts the most obvious expectation. - Prefer concrete guidance over internal type, module, or orchestration terminology. - Explain implementation details only when they help users make a decision or recover from a failure. - Distinguish supported behavior from recommendations and prospective behavior.