From 687f3260ea68e8ddf6f41f8fb01dc2a497f8033c Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 2 Sep 2026 20:41:44 -0400
Subject: [PATCH] docs(agents): defer writing rules to style guide

---
 AGENTS.md | 45 ++++-----------------------------------------
 1 file changed, 4 insertions(+), 41 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e7ec0b5..7f7dd6d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,12 +14,7 @@
 
 - Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
   Use the nearest project dictionary for project-specific domain language.
-- In authored prose, do not put multiple sentences on one physical line.
-  This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments.
-  A sentence can wrap across multiple physical lines when needed.
-- Keep Markdown formatting changes local.
-  Only format prose you write or change.
-  Never reflow an entire pre-existing paragraph or file because you touched nearby text.
+- Follow `docs/technical-writing.md` for authored prose, comments, and Markdown formatting.
 
 ## Pull requests
 
@@ -38,7 +33,7 @@
 
 ## Tooling
 
-- When a command is missing from the ordinary environment, prefer running it through Nix instead of installing it ad hoc.
+- When a command is missing from the ordinary environment, prefer running it through Nix instead of installing it for this case.
   For example, use `nix shell nixpkgs#python3 -c python3 <script>` for one-off Python commands.
 - Stage new files that Nix discovers through flake evaluation before testing.
   Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them.
@@ -67,41 +62,9 @@
 
 ## Comments
 
+- Follow `docs/technical-writing.md` for comments and authored prose.
 - Write comments only where they earn their place.
-  Keep comments concise.
-  Assume the reader can read code.
-  Explain why, not what.
-  Explain what only when it is genuinely non-obvious.
-- Keep comments self-contained to their file.
-  Write comments for a reader who sees only that file.
-  Do not explain how another file or tool consumes a value.
-  The only permitted cross-file mention is a bare pointer explaining why something is absent here.
-- Do not narrate history or future state in comments.
-  Avoid phrases such as "used to be", "now moved here", and "will be".
-  State the present reason a thing exists.
-- Do not justify a choice against alternatives in comments.
-  State the positive reason the choice exists.
-  Include present consequences when they matter.
-- Do not reference agent-facing state in comments.
-  This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`.
-- Do not use project-specific capitalized terms as glossary references in comments.
-  Use plain lowercase nouns unless the code requires the exact term.
-- Add a file-top header only when the filename or path does not already explain the file.
-  The header must be one concise purpose line.
-  Do not write a feature inventory.
-- Write placeholders plainly.
-  Include a present-tense action when one exists, such as `Placeholder: regenerate with <tool> on the target machine`.
-  Do not write `placeholder for <missing feature>`.
-- Treat user-facing documentation strings as documentation, not comments.
-  They can describe behavior more fully than code comments.
-  They still must stay self-contained and avoid agent-state references.
-- Start each sentence of a comment on its own physical line.
-  A comment sentence can wrap when needed.
-  Prefer splitting long comment sentences before wrapping them.
-  Do not break a line early at a comma or clause boundary to make it read as a unit.
-  Do not use semicolons in comments or authored prose.
-  Recast semicolon clauses as separate sentences.
-  Only reformat comments you write or change.
+  Comments must explain purpose, preconditions, invariants, or non-obvious consequences.
 
 ## Corrections