Repository navigation
Add writing guidance to AGENTS.md and apply it to docs - #5990
Merged
Merged
Conversation
Contributor
Author
rbev
approved these changes
Oct 12, 2026
rbev
left a comment
rbev
left a comment
Contributor
There was a problem hiding this comment.
Looks good
I mostly just reviewed agents.md and did a quick spot check on the rest of the changes to see what sort of changes it prompted.
| - Write a commit subject or pull request title as a short imperative summary of the change, without emoji or type prefixes; a squash merge turns the title into the commit subject. Give each commit one intent, and put renames and formatting changes in their own commits. | ||
| - Use formatting only where it helps scanning: sentence-case headings, lists for three or more parallel items, no bold label on every item, no emoji, and no dashes to join clauses in prose. Index entries and list items may be fragments, with a dash or colon between a term and its description. | ||
| - Do not invent facts, numbers, rationale, or sources. When the record does not say, write that it does not say. | ||
| - Leave out chat and drafting residue: offers, praise, and notes on how the text was produced or what it replaced. Keep provenance that changes how to read the text, such as a record reconstructed after the decision. Mention earlier behavior only where it explains the current design or a default, or in changelogs, release notes, and upgrade guides. |
Contributor
There was a problem hiding this comment.
👍 this is one of my pet peeves of AI doc writing.
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
2 participants
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.
Updates
AGENTS.mdto the current engineering context template and applies its new Writing section to the pages underdocs/.The template now has a Writing section that applies to pull request descriptions, commit messages,
docs/, ADRs, and code comments. It asks for the main point first, no restated or inflated text, short active sentences, one term per concept, and no invented facts. Commit subjects are short imperative summaries without emoji or type prefixes. Code comments explain only what the code cannot state.How the docs revision was made
An agent revised the docs using only the Writing section of
AGENTS.md, and the diff was reviewed by hand. Edits that removed information were reverted, such as contrasts that correct a likely assumption, history that explains a current default, and "should" in guidelines rewritten as a statement. Those cases led to the clarifications in the last commit.The docs commit also fixes typos, two broken link syntaxes, and British spellings, and converts headings to sentence case. Heading changes are case-only where other pages link to them, so anchors still resolve.
Commits
Review the commits separately.
AGENTS.mdis a verbatim copy of the template, and the docs commit changes wording, not meaning.Found but not changed
packaging.mdsaysRavenDBServer.zipis used by ServiceControl and Monitoring instances.deployment.mdand the project file comments say the primary and Audit instances.packaging.mdnames the zip folderzip, anddeployment.mdnames itzips. The repository haszip/.error-ingestion-design.mdsays the instance "runs a single ingestion loop today", which conflicts with the concurrent writers and--error-ingestion-onlyhosts iningestion-pipeline.md.data-versioning-design.mdrefers to "the reflection test above", but no test is described above it.testing.mdlinkspackaging.md#assembly-mismatches(the anchor is#assembly-version-mismatches) and/docs/test/ghcr-tag(the folder istest-ghcr-tag).forward-headers-testing.mdlinkstesting-architecture.md, which does not exist.