Skip to content

docs(agents): Rewrite the comment standard from what the compaction actually cut - #1028

Merged
omesser merged 1 commit into
mainfrom
docs/745-comment-standard
Sep 26, 2026
Merged

omesser merged 1 commit into
mainfrom
docs/745-comment-standard

Conversation

@omesser

@omesser omesser commented Sep 26, 2026

Copy link
Copy Markdown
Owner

Why

Agents still read a comment guide that quotes a five-line PERSONALITY_LIMIT block #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.md now 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, a ponytail: 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_LIMIT block #807 deleted, then the three lines that ship. The Dock note on a_walk_into_the_dock_climbs_onto_it_rather_than_behind_it is the citation-free constraint. The backup_path ponytail marker stays, with its ceiling, cost, and upgrade condition.

docs/agents/pstack.md is gone. The Code comments row in docs/agents/vendored-skills.md now 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.yml already says tightening it is a separate pull request, and module docs plus ponytail: markers still sit over 3 lines on purpose.

Out of scope. character/manifest.rs and character/resolve.rs still 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, and memory.rs on this branch.

node --test tests/*.test.js in this worktree: 343 passed, 0 failed, 1 skipped. pre-commit run --files docs/agents/comments.md docs/agents/vendored-skills.md passed. 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.

…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.
@omesser
omesser merged commit 32c1f02 into main Sep 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(agents): Rewrite the comment standard from what the compaction actually cut Comments are 20% of the tree: compact them to a stated bar

1 participant