| 1 | # Regex Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Dedicated playbook for reliable regular expression design, validation, and maintenance. |
| 5 | |
| 6 | **Knowledge cluster (syntax, engines, dialects, карта глав MRE3):** `index-knowledge-regex-cluster-v1.md` и `kb-regex-*` в этом каталоге; маршрутизация в `index-knowledge-router-v1.md` (секция `router-regex`). Загружать playbook первым, затем точечно один `kb-regex-*` по вопросу. |
| 7 | |
| 8 | ## Scope |
| 9 | - Pattern design and readability |
| 10 | - Dialect differences across engines |
| 11 | - Safety against false positives and destructive matches |
| 12 | - Test discipline for evolving patterns |
| 13 | |
| 14 | ## Evidence-Based Working Format |
| 15 | - Fact: capture concrete mismatch, parse failure, or overmatch. |
| 16 | - Hypothesis: define exactly how pattern change should fix behavior. |
| 17 | - Check: run pattern on representative positive and negative samples. |
| 18 | - Decision criterion: predefined accept/reject thresholds. |
| 19 | - Confidence mark: separate certainty from guesswork. |
| 20 | |
| 21 | ## Core Contracts |
| 22 | - Treat regex as code: document intent and boundaries. |
| 23 | - Prefer explicit anchors, groups, and boundaries over broad wildcards. |
| 24 | - Keep patterns reviewable; split complex intent into staged patterns if needed. |
| 25 | - Use named groups where supported for semantic clarity. |
| 26 | |
| 27 | ## Dialect Awareness |
| 28 | - .NET/PowerShell: engine semantics and options differ from POSIX tools. |
| 29 | - Bash toolchain: `grep/sed/awk` regex variants are not interchangeable. |
| 30 | - Python `re`: behavior differs from .NET in lookbehinds/options and flags. |
| 31 | - Always record target engine with the pattern. |
| 32 | |
| 33 | ## Safety Rules |
| 34 | - Validate against counterexamples before production use. |
| 35 | - Add guardrails when regex output drives file mutations. |
| 36 | - Avoid silent fallback behavior on no-match in destructive flows. |
| 37 | - Prefer parser logic over regex if grammar complexity becomes high. |
| 38 | |
| 39 | ## Testing Contracts |
| 40 | - Keep test fixtures for positive, negative, and edge samples. |
| 41 | - Include encoding and locale variants where relevant. |
| 42 | - Add regression tests for every bug-inducing pattern change. |
| 43 | - Record known non-goals explicitly. |
| 44 | |
| 45 | ## Metrics |
| 46 | - False-positive rate. |
| 47 | - False-negative rate. |
| 48 | - Time to diagnose regex-driven incidents. |
| 49 | - Number of regex changes without regressions. |
| 50 | |
| 51 | ## Revisit Triggers |
| 52 | - Repeated parsing incidents caused by pattern drift. |
| 53 | - Increasing pattern complexity with low readability. |
| 54 | - Frequent cross-engine incompatibility failures. |
| 55 | |
| 56 | |