Regex Builder

---
name: regex-builder
description: |
  Trigger when the user asks for help writing a regex, explaining a regex,
  or debugging a pattern. Phrases: "regex for", "match pattern", "explain
  this regex", "why doesn't this regex match".
allowed-tools:
  - Read
  - Write
  - Bash(node -e *)
---

# Regex Builder

Write and debug regular expressions for the target language's flavor.
Explain what the regex matches before shipping it.

## Prerequisites

- Sample input and expected matches
- Target language known (JS, Python, Go, PCRE all differ)

## Steps

1. **Get the sample.** Ask for at least three example inputs: one that
   should match, one that shouldn't, and one edge case.

2. **Build incrementally.** Start with the simplest regex that matches the
   first example. Add alternatives. Check against the no-match example.

3. **Use named captures and non-greedy quantifiers:**
   ```js
   /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/
   ```
   Named captures survive refactors better than positional groups.

4. **Anchor unless you mean not to.** Unanchored regexes find their pattern
   anywhere. Most use cases want `^...$` anchors.

5. **Test against edge cases.** Every regex has edge cases:
   - Empty input
   - Multi-line input (do you need `m` flag?)
   - Unicode (`u` flag in JS, `re.UNICODE` in Python)
   - Case (`i` flag or not)
   - Very long input (catastrophic backtracking)

6. **Watch for ReDoS.** Nested quantifiers (`(a+)+`) can take exponential
   time on crafted input. For user-supplied regexes, use a timeout or a
   non-backtracking engine (RE2).

7. **Write a test.** One regex plus one test array beats 20 minutes of
   manual verification. Keep the test in the repo next to the code.

## Explanation template

When explaining a regex, break it into labeled chunks:
```
^           - start of string
(\d{4})     - four digits (year)
-           - literal hyphen
(\d{2})     - two digits (month)
-
(\d{2})     - two digits (day)
$           - end of string
```

## Common requests with known answers

- Email (use a real library, not a regex)
- URL (use URL parsing, not a regex, unless you need syntactic match)
- ISO date -> `^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?Z?)?$`
- IPv4 -> `^(?:\d{1,3}\.){3}\d{1,3}$` with per-octet range check in code
- Slug -> `^[a-z0-9]+(-[a-z0-9]+)*$`

## Output

- Regex as a string or literal
- One-line explanation of what it matches and what it does not
- Three-example test: match, no-match, edge case