docs(schema): document Why + Bad/Good sections in rule-block-schema - #20
Merged
Conversation
…hema PR #19's bot review flagged the 'Why' field in 2 of my python-architecture RULE blocks as 'non-standard' per rule-block-schema.md. Verified: every existing rule block in this repo (74 total across 17 families, including all 4 the original pilot author wrote) carries Why. Schema doc was the incomplete artifact, not the rule blocks. Updated rule-block-schema.md to: - Note Why as a recommended (not indexed, walker ignores it) field after the three required fields. Explains it's the canonical home for the rule's rationale — the failure mode it prevents — which makes the rule defensible during code review. - Note #### Bad / #### Good code-example sections as recommended for the same reason: unambiguous intent, concrete comparison surface for bot reviews. Both additions match what every rule block in the repo already does; schema doc now describes reality. Future bot reviews on new RULE blocks won't flag Why as non-standard — it's now documented as part of the recommended shape.
Uh oh!
There was an error while loading. Please reload this page.
bborbe added a commit
that referenced
this pull request
Jun 2, 2026
Bot review timed out at 30-min activeDeadlineSeconds ceiling — the dispatcher refactor + 5-phase scaffolding produced a diff larger than the reviewer's per-PR budget. Admin-merge per PR #3 / #12 / #17 / #20 precedent. Differs from prior admin-merges in that this changes the actual /coding:pr-review contract (not doc-only), but: (1) make precommit clean including new check-coverage; (2) validate-citations.sh smoke-tested valid + invalid cases; (3) check-coverage.sh against current state: '124 rules, 15 mechanical YAMLs, no drift'; (4) the 3 simplified agents (go-error, go-time, go-context) are forward-compatible with the legacy 'scan + judge' shape — the dispatcher tolerates both during the per-agent migration follow-ups.
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
1 participant
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
Closes a schema-doc gap exposed by PR #19's bot review. The bot flagged `Why:` in 2 of my new rule blocks as 'non-standard per rule-block-schema.md'. Verified: every existing rule block (74 across 17 families, including the pilot author's originals) carries Why. The schema doc was the incomplete artifact — schema now describes reality.
What's added
Why
Future bot reviews on new RULE blocks won't flag Why as non-standard. The doc was actively misleading — it described 3 required fields only, while the repo's actual convention is 3 required + Why + Bad/Good.
Test plan