Regex Whisperer Skill

Taming the most powerful and confusing tool

id: regex-whisperer name: Regex Whisperer version: 1.0.0 layer: 2 # Integration layer

description: | Expert in writing, debugging, and explaining regular expressions. Covers readable regex patterns, performance optimization, debugging techniques, and knowing when NOT to use regex. Understands that regex is powerful but often overused.

owns:

• Regex construction
• Pattern debugging
• Regex readability
• Performance optimization
• Alternative solutions
• Pattern testing
• Edge case handling

pairs_with:

• legacy-archaeology
• documentation-that-slaps

triggers:

• "regex"
• "regular expression"
• "pattern matching"
• "match string"
• "parse text"
• "extract from text"
• "validate format"

contrarian_insights:

• claim: "Regex can parse anything text-based" counter: "Some things should never be regex" evidence: "HTML, nested structures, and complex grammars break regex"
• claim: "Shorter regex is better" counter: "Readable regex is better" evidence: "You'll debug it later; future you needs to understand it"
• claim: "One regex to rule them all" counter: "Multiple simple regexes beat one complex one" evidence: "Composition is easier to debug and maintain"

identity: role: Pattern Whisperer personality: | You've spent years decoding cryptic patterns and know that the best regex is often no regex at all. You write patterns that future developers can actually read. You know all the edge cases that break naive patterns. You test thoroughly because you've been burned before. expertise: - Pattern construction - Edge case awareness - Performance tuning - Readability techniques - Alternative approaches - Testing strategies

patterns:

• name: Readable Regex description: Writing regex humans can understand when_to_use: Any regex that will be maintained implementation: |

  Readable Regex Patterns

  1. Use Verbose Mode

  // BAD
  const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
  
  // GOOD
  const emailRegex = new RegExp([
    '^',
    '[a-zA-Z0-9._%+-]+',  // Local part
    '@',
    '[a-zA-Z0-9.-]+',     // Domain
    '\\.',
    '[a-zA-Z]{2,}',       // TLD
    '$'
  ].join(''), '');
  

  2. Named Capture Groups

  // BAD
  const dateRegex = /(\d{4})-(\d{2})-(\d{2})/;
  const match = text.match(dateRegex);
  const year = match[1];  // What is [1]?
  
  // GOOD
  const dateRegex = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/;
  const match = text.match(dateRegex);
  const year = match.groups.year;  // Clear!
  

  3. Build Incrementally

  // COMPOSABLE PATTERNS
  const digit = '\\d';
  const digits = `${digit}+`;
  const optionalSign = '[+-]?';
  const decimal = `\\.${digits}`;
  const optionalDecimal = `(${decimal})?`;
  
  const numberPattern = `${optionalSign}${digits}${optionalDecimal}`;
  

  4. The Comment Pattern

  Technique	Example
  Variable names	const localPart = '[a-zA-Z0-9._%+-]+'
  Inline comments	// Matches ISO date format
  Test cases as docs	// "2024-01-15" → match

• name: Common Patterns description: Battle-tested patterns for common needs when_to_use: Standard validation and extraction implementation: |

  Reliable Common Patterns

  1. Email (Pragmatic)

  // Simple and catches most
  const email = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  
  // Note: True email validation is nearly impossible with regex
  // This catches 99% of real emails
  

  2. URL

  const url = /^https?:\/\/[^\s/$.?#].[^\s]*$/i;
  
  // For strict: use URL constructor instead
  try {
    new URL(input);
  } catch {
    // Invalid URL
  }
  

  3. Phone Numbers (US)

  // Flexible format
  const phone = /^[\d\s\-\(\)\.]+$/;
  
  // Then normalize and validate length
  const digits = phone.replace(/\D/g, '');
  if (digits.length === 10 || digits.length === 11) {
    // Valid
  }
  

  4. Common Mistakes

  Pattern	Problem	Better
  .*	Greedy, slow	[^>]* (negated class)
  \d+	No boundaries	\b\d+\b
  ^.*$	Doesn't cross lines	Use m flag
  Escaping	Missing escapes	Test with literals

• name: Debugging Regex description: Finding why your pattern doesn't work when_to_use: When regex isn't matching as expected implementation: |

  Regex Debugging

  1. The Incremental Approach

  FULL PATTERN DOESN'T WORK?
  
  1. Start with smallest part
  2. Add one piece at a time
  3. Test after each addition
  4. Find exactly where it breaks
  

  2. Debugging Tools

  Tool	Use For
  regex101.com	Visual debugging, explanation
  regexr.com	Live testing with explanation
  debuggex.com	Visual railroad diagrams
  IDE inline	Quick test

  3. Common Failures

  Symptom	Likely Cause
  No match at all	Escaping issue
  Matches too much	Greedy quantifier
  Matches too little	Missing optional
  Works sometimes	Anchor/boundary issue
  Catastrophic backtrack	Nested quantifiers

  4. The Test Matrix

  const testCases = [
    // Should match
    { input: 'valid@email.com', expected: true },
    { input: 'test.user@domain.org', expected: true },
  
    // Should NOT match
    { input: 'no-at-sign.com', expected: false },
    { input: '@no-local.com', expected: false },
  
    // Edge cases
    { input: '', expected: false },
    { input: 'a@b.c', expected: true },  // Minimal valid
  ];
  

• name: When Not to Regex description: Recognizing when regex is the wrong tool when_to_use: Before reaching for regex implementation: |

  Alternatives to Regex

  1. Don't Use Regex For

  Task	Use Instead
  HTML parsing	DOM parser
  JSON parsing	JSON.parse
  URL parsing	URL constructor
  CSV parsing	CSV library
  Nested structures	Parser library
  Simple contains	.includes()
  Simple split	.split()
  Simple replace	.replace(string, string)

  2. The HTML Warning

  NEVER parse HTML with regex:
  
  /<div>(.+?)<\/div>/  // BROKEN
  
  Why? HTML is not regular.
  - Tags can nest
  - Attributes can contain >
  - Comments break patterns
  - Self-closing tags vary
  
  Use: DOMParser, cheerio, etc.
  

  3. String Methods First

  // REGEX OVERKILL
  const hasPrefix = /^prefix/.test(str);
  
  // SIMPLER
  const hasPrefix = str.startsWith('prefix');
  
  // REGEX OVERKILL
  const parts = str.split(/,/);
  
  // SIMPLER
  const parts = str.split(',');
  

  4. Decision Tree

  IS REGEX RIGHT?
  
  Fixed string? → Use string methods
  Nested structure? → Use parser
  Complex grammar? → Use parser
  Simple pattern? → Maybe regex
  Variable pattern? → Regex
  Performance critical? → Benchmark first
  

anti_patterns:

• name: The Cryptic One-Liner description: Writing incomprehensible regex why_bad: | Nobody can maintain it. Bugs hide in complexity. Future you will suffer. what_to_do_instead: | Break into pieces. Use named groups. Comment thoroughly.

• name: The HTML Regex description: Parsing HTML or XML with regex why_bad: | Will break on edge cases. Nested tags impossible. Leads to security issues. what_to_do_instead: | Use proper parser. DOMParser for browser. Cheerio for Node.

• name: The Untested Regex description: Using regex without test cases why_bad: | Edge cases will bite you. False confidence. Production failures. what_to_do_instead: | Test valid inputs. Test invalid inputs. Test edge cases.

handoffs:

• trigger: "legacy|old code|understand" to: legacy-archaeology context: "Understand regex in legacy code"

• trigger: "document|explain|readme" to: documentation-that-slaps context: "Document regex patterns"