All rules

R001 RationaleProse

Applies to
Rules files (CLAUDE.md, AGENTS.md, .mdc, .cursorrules, Copilot instructions, GEMINI.md, .windsurfrules)
Severity
Info (−1 per finding, max −30)
Summary
Instructions explain why instead of stating what.
Flags
"because", "so that", "in order to", "the reason", "this ensures", "this helps", "which means" in an instruction: a list item that contains an instruction sentence, or a paragraph sentence that is an instruction and the sentence after it. Instruction sentence: a clause opens with a directive word (always, never, must, do not …) or an imperative verb, optionally after "if / when / where / ideally … ,"; or a label opens with a directive word ("Be concise:"); or it contains must, should, shall, need to, have to, is required, you can / could / may / might, or do not (not after we / they / it / that …); or it is a list item of at most 12 words with no label, no verb form such as is / are / has / uses, and no leading determiner, pronoun or gerund ("- One concept per file."). Not instructions: list items labelled with inline code or an identifier (catalog entries); files with 20 or more MDX component lines (pasted documentation). Skipped: descriptive prose; HTML comments; quoted text; phrases after "/" or a quote mark; "just / only / simply / merely / solely / purely because"; "because of"; "the reason" as an object.
Measured false-positive rate
47% (14 of 30) and 40% (12 of 30), two judges, ruleset v4. Methodology
Known limits
"because" introducing a condition inside a prohibition ("never skip steps because a task seems small") is flagged as rationale. Suppress it with an in-file comment if the line is deliberate.
A descriptive sentence that shares a list item with an instruction is flagged as rationale. Suppress it with an in-file comment if the line is deliberate.

Before

- Use tabs because the formatter expects them.

After

- Use tabs.

Fix