Skip to content

docs(standards): document REVIEW.md as a required file - #92

Merged
sbaerlocher merged 1 commit into
mainfrom
feat/review-md-standards
Aug 9, 2026
Merged

docs(standards): document REVIEW.md as a required file#92
sbaerlocher merged 1 commit into
mainfrom
feat/review-md-standards

Conversation

@sbaerlocher

Copy link
Copy Markdown
Member

Summary

  • Adds REVIEW.md to the required-files list and the recommended structure tree in standards.rst; it exists in seven arillso repositories with an identical five-heading structure but was documented nowhere.
  • Documents what the file is for: ai-claude-review.yml in arillso/.github reads it on every pull request and treats it as taking precedence over generic best practices.
  • Documents the base-branch rule — the workflow reads the file from .review-base/ and ignores the copy at the repository root, so a pull request cannot rewrite the rules of its own review.
  • Specifies the five headings as the shared contract, with the severity levels table and guidance on writing the two repository-specific sections.

Test plan

  • Sphinx build succeeds (./build.sh) — not runnable in the authoring environment, left to CI
  • :ref: targets resolve: review-md is defined once and referenced from the workflow naming section and the seealso block

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found.

Reviewed the RST changes in rst/guide/best-practices/standards.rst:

  • Section underlines all meet/exceed title length (verified char counts).
  • :ref: label review-md defined once and referenced twice — no duplicate/broken refs.
  • Enumerated list sequential (1–10); file-tree entry correctly placed.
  • list-table, .. important::, and code-block directives well-formed.
  • Documented severity levels and five-heading contract are consistent with this repo's own REVIEW.md.

Build success and ref resolution are correctly deferred to CI.

REVIEW.md is consumed by the AI review workflow and overrides generic best
practices, but the guide never mentioned it — nobody setting up a repository
learned it existed or which five headings it must carry.

Signed-off-by: Simon Bärlocher <s.baerlocher@sbaerlocher.ch>
@sbaerlocher
sbaerlocher force-pushed the feat/review-md-standards branch from 25234a5 to 330e619 Compare August 9, 2026 10:17
@sbaerlocher
sbaerlocher enabled auto-merge (squash) August 9, 2026 10:17
@sbaerlocher
sbaerlocher merged commit 3793e4d into main Aug 9, 2026
6 checks passed
@sbaerlocher
sbaerlocher deleted the feat/review-md-standards branch August 9, 2026 10:20
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