The rules /code-review checks a diff against, alongside GLOSSARY.md and docs/adr/. Each rule is a judgement call that linting can't catch. Anything mechanical belongs in a check instead (lint, a test, the pre-commit hook or CI).
A configuration value the code parses (a split, a pattern, a number with a valid range) is checked where it's bound, in its @ConfigurationProperties setter or constructor. A bad value then stops the app from starting, rather than throwing on the first request that reads it. The parsed parts are kept on the properties class, and callers read them there.
Example: GitHubAppProperties.setSolutionRepositoryTemplate rejects anything other than owner/name, and solutionRepositoryTemplateOwner() / …Name() hold the parts.
A value with parts (owner/name, yyyy-MM, a slug path) is taken apart by one accessor on its type, and every caller uses that accessor. Each substring/split call site is a separate copy of the format, and the copies drift apart.
Example: GitHubRepo.name() gives codebite-solutions from octocat/codebite-solutions.
A test that guards data (every migrated Diagram, every Test Case) has cases showing wrong data failing it, one for each way the data can go wrong. Passing on today's data says nothing about the check, and a loose comparison passes on anything. Each exception the check allows gets a case just outside it that fails, since an exception is where wrong data slips through: an excuse for a value leaving gets a value arriving under the same excuse.
Example: DiagramsMatchExamplesTest.aWrongDiagramIsCaught holds a wrong Diagram for each way one could slip through: one row of a grid, a pinned Diagram under the wrong example, after copied from the input.
A guard that decides by parsing text (Markdown, SQL, a log) can also pass wrongly by losing its place: one line read as opening or closing a block, and everything after it is skipped. Its tests include input that is nested, unbalanced or malformed in a way that could make the guard skip what it should catch, and show the thing after it still caught.
Example: scripts/ship-branch.sh's unticked-box check first toggled "inside a code block" on any fence line, so a three-backtick line inside a four-backtick fence hid every real - [ ] after it and the PR would have merged (#248). scripts/ship-branch.test.sh now puts an unticked box after each such fence shape and expects the merge refused.
When "it isn't there" is what lets code delete, drop or flush something, a lookup that failed or came back empty for another reason is told apart from one that answered "absent", and stops the run. Read as absent, one failed query makes everything that exists look gone. A test feeds the lookup's failure and expects nothing deleted.
Example: existing_databases in scripts/dev-branch-servers.sh exits when the database list fails or lacks postgres. Before, a failed list read as "no database exists", and drop <name> would have deleted a live branch database's Kafka topics and flushed its Redis index (#418).
A test that needs a problem without some optional asset (a Walkthrough, a Diagram, a Solution, a Driver for a language) makes that state itself: it renames the problem to a Slug no file is named for, deletes the row, or uses a fixture. It doesn't name a real problem that lacks the asset today, since filling the gaps is ongoing work and the next ticket turns such a test red.
Example: WalkthroughEndpointTest renames rotting-donuts to a Slug with no Walkthrough file instead of naming snack-drawer-pair, which #264 gave one.
The same holds for the wrong data a guard test feeds its check: it builds a small fixture, never edits a real file at a fixed frame, row or key, since regenerating that file moves what the position holds and the case then fails for the wrong reason or passes without testing anything. WalkthroughsMatchSamplesTest's breakage cases each break a Walkthrough they build (walkthrough(...), step(...), varsFixture(); #296, #332).
A Diagram's highlight or highlight_path marks part of its example's answer, or the inputs the example asks about. A count or a time as the answer usually means no highlight. .claude/skills/add-diagram/SKILL.md has the rule; tests check only that a highlight exists in the Diagram.
Example: lca-bst highlights p and q; count-desk-clusters, whose answer is a count, highlights nothing.
.claude/skills/add-walkthrough/views.md has one section per Roadmap Category, in Roadmap order, after "Every view" and "Recursion and the call stack". Each bullet is one rule: a shape, how it is drawn, and the tracers that draw it. A Walkthrough that finds a new pattern edits the bullet it refines, or adds one bullet beside it in its category's section. It never adds a section named for a ticket or a second section for a category, and never states a rule another bullet already states: a bullet that needs another section's rule names that section. Two bullets stating one rule drift into two rules, and a reader can't tell which one holds. scripts/check-doc-references.py fails on the mechanical part, a ## heading with a ticket number or the same heading twice; a repeated rule is left to the reviewer.
Example: the Heap section's "A heap that only orders a search" points to Advanced Graphs, where the rule is. When each ticket of #364 appended a section of its own ("Greedy (#375)", "Dynamic Programming, part 2 (#376)"), the file ended with two Dynamic Programming sections and four heap rules that disagreed.