Scan

Mode 2: Board Position → FEN

Trigger: User provides a photo/screenshot of a chess board (physical board, screen, diagram)

Process:

1. Read the image using the Read tool (Claude's multimodal vision)
2. Identify each piece on each square SYSTEMATICALLY — go rank by rank, from rank 8 (top) to rank 1 (bottom), file a to h:
   • First: determine board orientation (look for coordinates on the edges, or assume white at bottom if unclear)
   • For each square: identify if empty, or piece type + color
   • Be extra careful with: bishops vs pawns (similar shape in some sets), knights vs other pieces, king vs queen
   • For digital screenshots (Lichess, Chess.com): piece recognition should be nearly perfect
   • For physical boards: lighting and angle affect accuracy, be more conservative and ask to confirm
3. Build the FEN string rank by rank:
   • White pieces: K Q R B N P (uppercase)
   • Black pieces: k q r b n p (lowercase)
   • Empty squares: count consecutive empties as a digit
4. Determine additional FEN fields:
   • Who is to move (ask user if unclear)
   • Castling rights (ask user if unclear — default to none if position looks mid-game)
   • En passant square (infer from pawn structure if possible)
5. Validate the position makes sense:

   python3 -c "
   import chess
   board = chess.Board('<FEN>')
   print(f'Valid: {board.is_valid()}')
   print(f'Pieces: {len(board.piece_map())}')
   print(board.unicode())
   "
   

6. Render the board back with our renderer and show to user:

   python3 tools/board_renderer.py "<FEN>"
   

7. Ask: "Does this match the position in your image?"
8. If user says no: ask which squares are wrong, fix, re-validate
9. If confirmed: offer to analyze with Stockfish or save

Output Format

Scoresheet scan output:

[Event "Club Tournament"]
[Date "2026.03.17"]
[White "Player 1"]
[Black "Player 2"]
[Result "1-0"]

1. e4 {[%clk 1:29:45]} e5 {[%clk 1:28:30]} 2. Nf3 Nc6 3. Bb5 a6 ...

Board scan output:

FEN: rnbqkb1r/pppppppp/5n2/4p3/2B1P3/8/PPPP1PPP/RNBQK1NR w KQkq - 2 3

[Board rendered in terminal for confirmation]

Error Handling

• Illegible moves: "I can't read move 15. It looks like it could be Nf3 or Nf5. Which one?"
• Illegal position: "Move 23 (Bxe5) is illegal in this position. The bishop is on c1, not on a diagonal to e5. Did you mean Nxe5?"
• Ambiguous pieces: "On d4, is that a white queen or white king? The image is unclear."
• Missing result: "I couldn't find the game result on the scoresheet. How did the game end?"

MANDATORY: Validation Gate Before Analysis

NEVER hand off to GM or any other agent until the user explicitly confirms the scan is correct.

The flow is always:

1. Scan the image → generate PGN or FEN
2. Render the result back to the user using board_renderer.py — ALWAYS use python3 tools/board_renderer.py "<FEN>" to show the board in the terminal. For PGN, render the final position AND any critical positions. Never show just text — always render the board visually.
3. Ask for explicit confirmation: "Is this correct?"
4. If user says no → ask what's wrong, fix, re-render, ask again
5. If user says yes → ONLY THEN offer to save/analyze
6. If user doesn't respond to the confirmation → do NOT proceed to analysis. Wait.

This gate exists because image recognition can make mistakes. Sending wrong data to GM wastes time and produces misleading analysis.

After Confirmation

Once the user has explicitly confirmed the PGN or FEN is correct:

1. Ask: "Want me to save this to your vault?"
2. Ask: "Want me to analyze this game/position?"
3. If user says yes to analysis, hand off to the coach skill which dispatches GM + Mind

Instructions

• Always respond in the user's language
• Be patient with unclear handwriting — propose your best reading and ask for confirmation
• ALWAYS validate the PGN by replaying moves before presenting it
• For board positions, ALWAYS render the board back and ask for confirmation
• NEVER skip the confirmation step — no exceptions
• When clock times are partially available, include them where present and omit where not — don't invent times
• If the scoresheet has annotations (!, ?, etc.), preserve them in the PGN