Skip to content

rules: the implementation outranks the documentation - #30

Merged
shinaoka merged 1 commit into
mainfrom
rules/code-outranks-docs
Oct 30, 2026
Merged

shinaoka merged 1 commit into
mainfrom
rules/code-outranks-docs

Conversation

@shinaoka

Copy link
Copy Markdown
Member

Adds an explicit precedence rule, because agents follow whatever a document asserts.

What changed

  • rules/index.md now 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.md gains the operational procedure: verify against the code and CI, never edit code to satisfy stale prose, correct or file the document with a file:line reference, 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:

  • a design note still presented the removed CubeCL backend as the current GPU contract,
  • an architecture page still assigned the primitive AD registry to tenferro-internal-ops, whose registry has no callers outside its own dead tree,
  • a performance guide still described a thread pool API that the caller held engine had replaced.

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.

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.
@shinaoka
shinaoka merged commit 0604ce0 into main Oct 30, 2026
1 check passed
@shinaoka
shinaoka deleted the rules/code-outranks-docs branch October 30, 2026 23:58
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.

1 participant