docs: sync AGENTS.md coding-output rules from distillery proof-2 (minimal-touch + two-variety comments) #481

New issue

Closed

opened 2026-08-09 05:04:44 +00:00 by igor · 0 comments

igor commented

2026-08-09 05:04:44 +00:00

Collaborator

Deliverables

In AGENTS.md, replace the line:

- Keep changes focused on the issue. Don't refactor unrelated code.

with:

- **Touch only what the task requires. No cleanup for its own sake.**
  No reformatting lines the change doesn't own, no drive-by renames,
  no opportunistic refactors or tidying, no fixing unrelated problems
  (mention those in the PR body instead). The diff should read as the
  task and nothing else.

In AGENTS.md, replace the entire "Comment discipline." bullet (begins - **Comment discipline.** A comment exists only to state something and ends ...is correct, not a gap to fill.) with:

- **Comment discipline. Code is the documentation; comments are the
  exception, not the norm.** Exactly two kinds are legal: (1)
  standard API doc comments in the language's own convention (JSDoc,
  godoc, docstrings) on public/exported surfaces; (2) a short
  comment stating a non-obvious *why* -- a constraint, an invariant,
  a workaround for a specific bug. Never narrate *what* the next
  line does ("call the helper", "loop over the results"), never
  write changelog-style comments ("added X for Y"), never restate a
  self-explanatory name in prose, and never leave review residue in
  code ("addressed feedback", "fixed per review" -- that belongs on
  the PR thread). If a comment restates the code, delete the
  comment. Zero comments on self-explanatory code is correct, not a
  gap to fill.

Out of scope

Any other AGENTS.md section, any code, any other file. This is a two-hunk prose sync.

Verification

make test passes (check-sync asserts the OUTCOME sentinel contract -- untouched sentinels prove the edit stayed surgical).
git diff shows exactly two hunks in exactly one file.

Distillery (the context brain, joshtronic/distillery) has dialed in the worker contract's coding-output rules at proof-2; igor's live copy must match. Apply these two exact text replacements to `AGENTS.md`. Nothing else changes -- the OUTCOME sentinels and every other section stay untouched. ## Deliverables 1. In `AGENTS.md`, replace the line: `- Keep changes focused on the issue. Don't refactor unrelated code.` with: ``` - **Touch only what the task requires. No cleanup for its own sake.** No reformatting lines the change doesn't own, no drive-by renames, no opportunistic refactors or tidying, no fixing unrelated problems (mention those in the PR body instead). The diff should read as the task and nothing else. ``` 2. In `AGENTS.md`, replace the entire "**Comment discipline.**" bullet (begins `- **Comment discipline.** A comment exists only to state something` and ends `...is correct, not a gap to fill.`) with: ``` - **Comment discipline. Code is the documentation; comments are the exception, not the norm.** Exactly two kinds are legal: (1) standard API doc comments in the language's own convention (JSDoc, godoc, docstrings) on public/exported surfaces; (2) a short comment stating a non-obvious *why* -- a constraint, an invariant, a workaround for a specific bug. Never narrate *what* the next line does ("call the helper", "loop over the results"), never write changelog-style comments ("added X for Y"), never restate a self-explanatory name in prose, and never leave review residue in code ("addressed feedback", "fixed per review" -- that belongs on the PR thread). If a comment restates the code, delete the comment. Zero comments on self-explanatory code is correct, not a gap to fill. ``` ## Out of scope - Any other AGENTS.md section, any code, any other file. This is a two-hunk prose sync. ## Verification - `make test` passes (check-sync asserts the OUTCOME sentinel contract -- untouched sentinels prove the edit stayed surgical). - `git diff` shows exactly two hunks in exactly one file.

igor added the

Agent

label

2026-08-09 05:04:44 +00:00

igor self-assigned this

2026-08-09 05:08:07 +00:00

igor referenced this issue from a pull request that will close it,

2026-08-09 05:10:07 +00:00

docs: sync AGENTS.md coding-output rules from distillery proof-2 #483

igor added spent time

2026-08-09 05:10:08 +00:00

1 minute 51 seconds