Repository navigation
rules: the implementation outranks the documentation - #30
Merged
Merged
Conversation
Agents follow whatever a document asserts, so a stale paragraph about a removed mechanism is more damaging than a missing paragraph. State the precedence explicitly at the top of the index, and give the operational procedure in the docs rules: verify behaviour against the code, tests and CI; never edit code to satisfy stale prose; fix or file the document with a file:line reference; and retire the describing documents in the same change as the implementation. Recent examples in this organisation: a design note still presented the removed CubeCL backend as the current GPU contract, an architecture page still assigned the primitive AD registry to a crate whose registry has no callers, and a performance guide still described a thread pool API that the caller held engine replaced.
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.
Adds an explicit precedence rule, because agents follow whatever a document asserts.
What changed
rules/index.mdnow opens with The Implementation Outranks The Documentation: the code, its tests and the CI configuration define current behavior, and a stale statement is a defect to fix rather than an instruction to follow.rules/common/docs-and-tests.mdgains the operational procedure: verify against the code and CI, never edit code to satisfy stale prose, correct or file the document with afile:linereference, treat required reading, ownership pages and source of truth claims as high risk, and retire the describing documents in the same change as the implementation.Why
Three concrete failures in this organisation came from prose that outlived its code:
tenferro-internal-ops, whose registry has no callers outside its own dead tree,Each one misdirected an agent that was following the rules correctly. Fixing the code was never the right response; correcting the documents was.
82 of the repositories under the organisation reference this index from their own
AGENTS.md, so the rule reaches them without editing each repository.