what

• add a new subsection Avoiding Catastrophic Backtracking (Ambiguity) to the "Writing Regular Expressions" part of CONTRIBUTING.md

why

• the existing guidance covers lazy quantifiers and the RE2 (non-backtracking) restrictions, but does not explain the actual root cause of catastrophic backtracking in CRS regexes: ambiguity inside a quantified group, not greediness. since CRS cannot use atomic groups or possessive quantifiers, writing unambiguous expressions is the only available defense.
• the new subsection documents the guiding principle (inside a quantified group, every input character should be consumable by exactly one branch/position, and each whitespace run in exactly one place), the two ambiguous shapes that show up most often (a \s branch next to a comment body that also matches whitespace; a token wrapped in \s* on both sides inside a repeated group), and a before/after example.
• it also records two CRS-specific testing notes that are easy to get wrong: test with . matching newlines (DOTALL, as ModSecurity runs @rx), and treat PCRE2 exceeding its backtracking limit (which errors and makes the rule fail to match) as the meaningful signal, rather than a checker's theoretical "exponential" label (RE2 is immune; PCRE2's required-literal optimization tames many theoretically-ambiguous cases).

refs

• documentation only; no rule or test changes

ai disclosure

• tools used: Claude (Opus 4.8)
• assisted with: drafting the CONTRIBUTING.md subsection wording and the before/after example
• review performed: the principle and examples were derived from empirical analysis of existing CRS rules (measuring backtracking growth under DOTALL on Python re and PCRE2 grep -P); the before/after example is a real de-ambiguation verified to be flat on both engines while preserving functional matches