Skip to content

docs(standards): fix the block's H1 and the false default-reviewer claim (backend#1602) - #179

Merged
LukasWodka merged 1 commit into
developfrom
docs/1602-standards-heading-and-reviewer-claim
Aug 6, 2026
Merged

docs(standards): fix the block's H1 and the false default-reviewer claim (backend#1602)#179
LukasWodka merged 1 commit into
developfrom
docs/1602-standards-heading-and-reviewer-claim

Conversation

@LukasWodka

@LukasWodkaLukasWodka commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

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 consuming CLAUDE.md already has # CLAUDE.md as 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.md statement 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:

You pick the reviewer: whoever knows the code best. There is no per-repo default, and no automation assigns one — branch protection just refuses to merge without a review.

Test plan

  • scripts/tests/standards-sync-selftest.py20 checks, 0 failed
  • Once this lands, standards-sync.py --create-prs refreshes 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 canonicalorg-standards.md block that syncs into every repo’s CLAUDE.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.md title and avoids a second top-level H1 (markdownlint MD025).

Reviewer policy: The Branches & PRs bullet no longer says each repo’s CLAUDE.md names 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.

…-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>
@LukasWodkaLukasWodka self-assigned this Aug 6, 2026
@LukasWodka
LukasWodka merged commit 4400096 into developAug 6, 2026
13 of 16 checks passed
@LukasWodka
LukasWodka deleted the docs/1602-standards-heading-and-reviewer-claim branch August 6, 2026 13:39
Sign up for freeto 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.

2 participants

@LukasWodka@saadqbal