From cd0f4fabf91647d5bbb5f2ee7d8448e9e45d53cd Mon Sep 17 00:00:00 2001 From: Benjamin Borbe Date: Tue, 2 Jun 2026 16:46:14 +0200 Subject: [PATCH] docs(schema): document Why field + Bad/Good sections in rule-block-schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/rule-block-schema.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/rule-block-schema.md b/docs/rule-block-schema.md index 3a44f89..a5cae2d 100644 --- a/docs/rule-block-schema.md +++ b/docs/rule-block-schema.md @@ -4,7 +4,7 @@ Authoritative reference for the `### RULE` block contract in `docs/*.md` files a ## ### RULE Block Contract -A rule block is a level-3 Markdown heading (`### RULE`) followed by three required field lines. The walker extracts these into `rules/index.json`. +A rule block is a level-3 Markdown heading (`### RULE`) followed by three required field lines, a recommended `Why` paragraph, and Bad/Good code examples. The walker extracts the three required fields into `rules/index.json`. #### Heading Format @@ -32,6 +32,21 @@ Immediately beneath the heading, three fields must appear, each on its own line: - **Applies when**: Describes the condition under which the rule fires. - **Enforcement**: Describes how the rule is enforced — typically a path to an ast-grep rules file plus any LLM-adjudication notes. +### Recommended Field: `Why` + +Most rule blocks in this repo carry a `**Why**:` paragraph immediately after `**Enforcement**:`. The `Why` is not indexed (the walker ignores it) but is highly recommended as the *only* place the rule's rationale lives — it tells future authors, agents, and bot reviewers *what failure mode this rule prevents*, which is what makes the rule defensible during code review. + +```markdown +**Why**: +``` + +Omit `Why` only when the rule's rationale is genuinely self-evident from the rule ID and the Bad/Good examples — which is rare. Every rule shipped to date in this repo carries it. + +### Recommended Sections: Bad / Good Examples + +After the field block, every rule block in this repo carries `#### Bad` and `#### Good` code examples that show the violation and the fix. These are not indexed but are essential for human readers and bot review: they make the rule's intent unambiguous and give the bot something concrete to compare review findings against. + ### Level Tokens | Token | Meaning |