Uh oh!
There was an error while loading. Please reload this page.
docs(standards): fix the block's H1 and the false default-reviewer claim (backend#1602) - #179
Merged
LukasWodka merged 1 commit intoAug 6, 2026
Conversation
…-repo default reviewer @saqlainsyed007 raised both on the sync PRs (backend#1611, averaging-service#308), and both are source-side: the block must not be hand-edited in a consuming repo. 1. The block opened with an H1 while every consuming CLAUDE.md already has '# CLAUDE.md' as its sole title. Two H1s break the outline and trip markdownlint MD025. Every heading is demoted one level so the standards nest as a section under the host document's title. 2. 'Each repo's CLAUDE.md names its default reviewer' is false fleet-wide -- no repo names one -- and it contradicts the org's actual model, which is author-picks-reviewer with no automation assigning anyone. The line now describes what we really do, so the rule above it is actionable. Selftest: 20 checks, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
saadqbal
approved these changes
Aug 6, 2026
Uh oh!
There was an error while loading. Please reload this page.
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 freeto 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.
Summary
Both fixes @saqlainsyed007 raised on the sync PRs (backend#1611, averaging-service#308). He correctly identified both as source-side: the synced block must never be hand-edited in a consuming repo, so fixing it in the 18 open sync PRs would have been the wrong move.
1. Second H1 (markdownlint MD025). The block opened with
# tracebloc engineering standards (org-wide)while every consumingCLAUDE.mdalready has# CLAUDE.mdas its sole title. Two H1s in one document read as two document titles and break the outline. Every heading is demoted one level, so the standards nest as a section under the host doc's title.2. The default-reviewer claim was false. The block asserted "Each repo's CLAUDE.md names its default reviewer" — and no repo does. Worse, it contradicts the org's actual model (RFC-BACKEND-0008 D31: author-picks-reviewer, no automation assigns anyone). Its own closing rule says a change making a
CLAUDE.mdstatement false must be corrected in the same PR, so the block was self-violating.Rather than add a fabricated default reviewer to 18 repos, the line now describes what we really do:
Test plan
scripts/tests/standards-sync-selftest.py— 20 checks, 0 failedstandards-sync.py --create-prsrefreshes all 18 open sync PRs against the corrected canon. They are DRIFTED until then, which is the expected state the script's own docstring describes.🤖 Generated with Claude Code
Note
Low Risk
Documentation-only change to the canonical standards snippet; no runtime, auth, or deployment behavior is affected.
Overview
Updates the canonical
org-standards.mdblock that syncs into every repo’sCLAUDE.md, so consuming docs stay valid and accurate after the next standards-sync run.Heading structure: The block title and section headings are demoted one level (
#→##,##→###) so the synced content nests under each host file’s existing# CLAUDE.mdtitle and avoids a second top-level H1 (markdownlint MD025).Reviewer policy: The Branches & PRs bullet no longer says each repo’s
CLAUDE.mdnames a default reviewer. It now states that the author picks whoever knows the code best, there is no per-repo default and no automation assigns a reviewer, and branch protection still requires a review before merge.Reviewed by Cursor Bugbot for commit 18e1c03. Bugbot is set up for automated code reviews on this repo. Configure here.