regex-chess

name	regex-chess
description	Guidance for generating legal chess moves using only regex pattern matching and substitution. This skill applies when implementing chess move generators constrained to regex-only solutions, FEN notation parsing/manipulation, or similar pattern-matching-based board game logic. Use this skill for tasks requiring regex-based state transformations on structured string representations.

Regex Chess

Overview

This skill provides strategic guidance for implementing chess move generators using only regular expressions. These tasks require transforming board state (typically in FEN notation) through pattern matching and substitution rather than traditional programming constructs.

Core Approach

Phase 1: Understand the String Representation

Before writing any patterns, thoroughly understand the board representation:

1. Parse the FEN structure: FEN notation encodes rank 8 to rank 1 (top to bottom), with files a-h (left to right) within each rank
2. Map coordinates to string positions: Determine the exact character index for each square after expanding digit placeholders (e.g., "8" becomes "........")
3. Document the ordering: Create a clear mapping of how squares appear sequentially in the expanded string

Phase 2: Start Minimal - One Move Type First

Critical: Get a single move type working completely before adding complexity.

Recommended order:

1. Start with a single pawn push (e.g., e2-e4)
2. Verify the pattern matches correctly
3. Verify the replacement produces correct output
4. Only then add more pawn moves
5. Only after all pawn moves work, add knights (simplest piece with no sliding)
6. Add remaining pieces incrementally

Phase 3: Coordinate Labeling Strategy

To simplify pattern matching, consider adding coordinate labels to the expanded board:

Original: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
Expanded with labels: R8:a8r.R8:b8n.R8:c8b...R1:h1R.

This makes patterns self-documenting and reduces coordinate confusion.

Phase 4: Pattern Structure

For each move pattern:

1. Capture groups for context: Use groups to preserve surrounding board state
2. Source square pattern: Match the piece at its origin
3. Destination square pattern: Match the target (empty or enemy piece)
4. Replacement string: Reconstruct with piece moved, preserving all other state

Verification Strategies

Test Each Transformation Step

1. Pattern matching verification: Confirm the pattern matches the expected input
2. Replacement output verification: Confirm the substitution produces correct output
3. Round-trip verification: Verify the output FEN is valid and represents the intended move

Incremental Testing Protocol

For each new move pattern:
1. Test on known position with expected outcome
2. Verify exactly ONE move is generated
3. Verify the move is the CORRECT move
4. Only then add to the full pattern set

Debug Output Format

When debugging, output intermediate states:

• The expanded board string before matching
• Which pattern matched
• The captured groups and their values
• The replacement string before compression
• The final FEN output

Common Pitfalls

Coordinate Ordering Errors

Problem: Squares appear in a specific order in the FEN string (rank 8 first, then 7, etc.). When matching two squares, the "earlier" square in the string depends on their coordinates, not their role in the move.

Solution: When a pattern needs to match source and destination squares, determine which appears first in the string based on coordinates, not based on which is source vs. destination.

Group Numbering Confusion

Problem: Using \1, \2, etc. in replacements without tracking which group corresponds to which board region.

Solution: Comment each pattern with explicit group assignments:

# Group 1: everything before source square
# Group 2: source square piece
# Group 3: everything between source and dest
# Group 4: destination square
# Group 5: everything after destination

Premature Pattern Generation

Problem: Generating thousands of patterns before verifying the basic infrastructure works.

Solution: Generate patterns incrementally. Verify 1 pattern works, then 10, then 100, etc.

Abandoning Partial Solutions

Problem: When something partially works, starting over with a "better" approach that breaks everything.

Solution: When you have partial success (e.g., 3/3 moves correct for a test position), preserve that working code. Add to it rather than replacing it.

Format Issues vs. Logic Issues

Problem: Spending excessive time on output formatting (trailing spaces, move counters) before the core logic works.

Solution: Get the board transformation correct first. Format adjustments are a final step.

Testing Pattern Matching Without Replacement

Problem: Verifying that patterns "match" but not verifying the replacement output is correct.

Solution: Always check both: (1) does it match? (2) is the replacement correct?

Implementation Checklist

Before running full tests:

• One simple move (e.g., e2-e4) works end-to-end
• All pawn single pushes work
• Pawn captures work
• Knight moves work (no sliding complexity)
• Bishop/Rook/Queen sliding moves work
• King moves work
• Edge cases: moves near board edges

Features often deferred (verify requirements):

• Move legality (king not in check after move)
• Castling with proper rights tracking
• En passant
• Pawn promotion
• Double pawn push with en passant square update

Debugging Workflow

When a move is incorrect:

1. Isolate the failing case: Test with only that one pattern
2. Print the expanded board: Verify the input is as expected
3. Print captured groups: Verify each group contains what you expect
4. Print the raw replacement: Before any compression or formatting
5. Compare to expected: Character by character if needed

Avoid:

• Running full test suite repeatedly without isolating the issue
• Adding more patterns before fixing existing ones
• Rewriting from scratch when debugging would suffice