Repository navigation
docs(agents): Rewrite the comment standard from what the compaction actually cut - #1028
Merged
Merged
Conversation
…ctually cut The guide still quoted the five-line PERSONALITY_LIMIT block #807 deleted, and it still told agents an issue number was worth keeping. The page now states the 3-line bar, the exceptions, and quotes that match the tree. The collision row points at that bar. pstack.md is gone. The row lives in vendored-skills.md. Closes #745. Refs #744.
This was referenced Sep 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Agents still read a comment guide that quotes a five-line
PERSONALITY_LIMITblock #807 deleted, and that tells them an issue number is worth keeping. The compaction children already cut to a shorter bar. The guide was the page that would grow the long comments back.What changed
docs/agents/comments.mdnow states a 3-line default. A public item keeps a one-line summary. A//!module header stays exempt. A block may run longer for a weird implementation, aponytail:marker, a bound that looks arbitrary, or a rejected alternative.The page says code comments are not audit logs. A bare issue or ADR number stays only when the code is not understandable without opening it. The worked pair is the
PERSONALITY_LIMITblock #807 deleted, then the three lines that ship. The Dock note ona_walk_into_the_dock_climbs_onto_it_rather_than_behind_itis the citation-free constraint. Thebackup_pathponytail marker stays, with its ceiling, cost, and upgrade condition.docs/agents/pstack.mdis gone. The Code comments row indocs/agents/vendored-skills.mdnow points at the 3-line bar and still forbids/no-comments.The ast-grep ceiling stays at 20 lines.
scripts/ast-grep/rules/comment-blocks.ymlalready says tightening it is a separate pull request, and module docs plusponytail:markers still sit over 3 lines on purpose.Out of scope.
character/manifest.rsandcharacter/resolve.rsstill wait on #689. The Settings files #706 deletes stay untouched. This does not close #744.How to verify
The fenced comments that claim to be current source match
character.rs,engine.rs, andmemory.rson this branch.node --test tests/*.test.jsin this worktree: 343 passed, 0 failed, 1 skipped.pre-commit run --files docs/agents/comments.md docs/agents/vendored-skills.mdpassed. CI skips the node suite on a Markdown-only pull request, which is why the local run is the check.Closes #745
— Grok Build agent, on @omesser's behalf.