Regex architect

Regex Architect

Overview

Build correct, readable, and safe regular expressions, then prove they work. Keywords: regex, regular expression, pattern matching, ReDoS, catastrophic backtracking, validation, extraction, capture group, named group, lookahead, lookbehind, anchor, Unicode, PCRE, RE2, flavor portability.

This skill exists because regex is easy to write and hard to write well. Naive patterns silently accept bad input, reject good input, or hang a server when fed an adversarial string. The job is not just "produce a pattern" — it is to produce a pattern that is anchored correctly, scoped to the right flavor, free of exponential backtracking, and accompanied by a test plan.

Use this skill whenever a task involves matching, extracting, replacing, splitting, or validating text with a pattern — or explaining/debugging an existing one.

Core Principles

1. Clarify before constructing. Know the flavor, the input source, whether you are validating (whole string) or searching (substring), and what counts as valid. Ambiguity here produces wrong regexes.
2. Anchor on purpose. Validation almost always needs ^...$ (or \A...\z). Search/extract usually must NOT be anchored. Mismatched anchoring is the #1 correctness bug.
3. Prefer explicit character classes over . . is greedy, matches almost anything, and is a backtracking magnet. Use [^"], [^\n], \d, etc.
4. Make quantified subpatterns mutually exclusive. Overlapping alternations or nested quantifiers ((a+)+, (a|a)*, (.*)*) cause catastrophic backtracking.
5. Readability is a feature. Use named groups, verbose/extended mode, and comments for anything non-trivial. A regex nobody can edit is a liability.
6. Validate with structured logic when regex is the wrong tool. Do not regex HTML, nested brackets, or full email RFC 5322. Say so and offer a parser.

Workflow

1. Gather requirements (see references/clarifying-questions.md):
   • Target flavor / language runtime.
   • Validation vs. search vs. replace vs. split.
   • Exact set of valid and invalid examples (ask for at least 2 of each).
   • Multiline? Unicode? Case sensitivity? Performance constraints / untrusted input?
2. Choose a strategy. Pick character classes, anchoring, and grouping. Consult references/patterns-cookbook.md for vetted building blocks rather than inventing from scratch.
3. Draft the pattern in the requested flavor. Use named capture groups and, for non-trivial patterns, provide a verbose/commented version too.
4. Audit for ReDoS using the checklist in references/redos-guide.md. Rewrite nested/overlapping quantifiers; prefer atomic groups, possessive quantifiers, or bounded {0,n} quantifiers. If the runtime is RE2/Go/Rust, note it is already linear-time and lookarounds/backrefs are unsupported.
5. Explain it. Provide a token-by-token breakdown so the user can maintain it.
6. Test it. Run scripts/regex_test.py with positive and negative cases. It also runs a lightweight ReDoS timing probe. Report pass/fail per case.
7. Note portability. If the user may switch flavors, flag flavor-specific constructs (lookbehind, named-group syntax, \d Unicode semantics, inline flags) per references/flavor-portability.md.

Quick Decision Framework

• "Is this string entirely valid?" → anchor with ^$ (or \A\z); use re.fullmatch in Python.
• "Find all occurrences." → no anchors; use global/findall; mind overlapping matches.
• "Untrusted/large input?" → prioritize linear-time design; consider RE2-family engine; cap input length before matching.
• "Nested or recursive structure (HTML, JSON, code)?" → do NOT use regex; use a parser.
• "Just needs a yes/no on a simple format?" → small anchored class-based pattern.

Worked Example (short)

Validate a US ZIP (5 digits, optional -####), JavaScript:

/^\d{5}(?:-\d{4})?$/

• ^ / $ anchor the whole string.
• \d{5} exactly five digits.
• (?:-\d{4})? optional non-capturing group: hyphen + four digits.

Why it is ReDoS-safe: fixed-count quantifiers, no nested/overlapping repetition. See examples/worked-example.md for a full email-validation walkthrough including a naive-vs-safe comparison and test output.

Best Practices

• Always provide both the raw pattern and a one-line explanation of anchoring intent.
• Use non-capturing groups (?:...) unless you need the capture; name the ones you keep.
• For validation, return whole-string semantics explicitly (fullmatch, \A...\z, or ^...$ with the right flags).
• Escape user-provided literals; never interpolate raw user input into a pattern.
• Cap input length and/or set engine timeouts when matching untrusted data.
• Offer a verbose/x-mode version for any pattern longer than ~40 chars.
• Prefer [0-9] over \d when you must exclude non-ASCII digits (\d matches Unicode digits in many flavors).

Common Pitfalls

• Unanchored validation — /\d{5}/ matches inside abc12345xyz. Anchor it.
• Greedy .* across delimiters — <.*> over <a><b> grabs everything; use <[^>]*> or lazy <.*?> with care.
• Nested quantifiers — (\d+)+, (a*)*, (.*,)* → catastrophic backtracking.
• Unescaped dot/metachars in literals — 3.14 matches 3x14; escape to 3\.14.
• ^/$ with multiline — they match line boundaries under m; use \A/\z (or \Z) for true string ends.
• Backreferences/lookbehind in RE2/Go/Rust — unsupported; redesign.
• Trying to regex HTML/recursive grammars — wrong tool; use a parser.
• \b word-boundary surprises — depends on \w definition and Unicode mode.

Bundled Files

• references/patterns-cookbook.md — vetted, safe patterns for common formats with notes and traps.
• references/redos-guide.md — how catastrophic backtracking happens and how to fix it.
• references/flavor-portability.md — cross-flavor syntax differences and a mapping table.
• references/clarifying-questions.md — the question set to ask before writing a pattern.
• scripts/regex_test.py — runnable Python tester for positive/negative cases plus a ReDoS timing probe.
• examples/worked-example.md — end-to-end email-validation example with test output.