chess-postmortem-skills

---
name: chess-analysis
description: Engine post-mortem of a chess game producing a deeply annotated PGN. Runs a Stockfish eval sweep, then interrogates the engine with "naive questions" (via parallel investigator subagents) until every mistake and every complex engine move is genuinely explained, and writes layered annotations (short notes on ordinary moves, deep dives on 0.3+ pawn errors). Use whenever the user asks to analyze/review/annotate a game, find their mistakes, run a post-mortem or "stage 2", asks "where did I go wrong", or after a game played with the chess-play skill ends. Also for analyzing any PGN file the user provides. If the user recorded themselves thinking aloud during the game (a voice memo / mp3 alongside the game), this skill also covers transcribing it locally, clock-aligning it to the moves, and weaving the player's actual beliefs into the annotations.
---

# Chess post-mortem: sweep, interrogate, annotate

Goal: an annotated PGN a human learns from. An eval number is not an
explanation — the deliverable is the *why*, verified against the engine
and against your own eyes (render positions, look at them).

## Pipeline overview

0. **Audience** — whose game this is and what level to write for.
1. **Setup** — engine + venv.
2. **Sweep** — eval every move, flag mistakes (≥0.3 pawn loss).
3. **Investigate** — one subagent per mistake, in parallel, running the
   naive-question method (see below).
3b. **Plan pause** — exactly one quiet position per game, both sides'
   plans derived from the engine.
4. **Brief comments** — a subagent pass giving short notes to the
   ordinary moves.
5. **Build** — merge everything into `annotations.json`, run
   `build_annotated.py`, validate.
6. **Verify** — a subagent re-checks the artifact against the checklist.
7. **Viewer** — bundle the annotated PGN + sweep + engine-line sidecars
   into a standalone HTML analysis board (`build_viewer.py`).
8. **Deliver** — send the PGN and the HTML viewer, summarize findings in
   chat, commit if in a real repo session.

## 0. Who the review is for — settle this before writing anything

Every comment in this pipeline is pitched at a reader. Pick the level
first and record it, or the annotations drift into proving things the
player can already see.

- **The user's own games**: use the level the user gave you (ask once if
  you don't know it, and remember the answer: a CLAUDE.md line or a memory
  note such as "my lichess handle is X, write for 1800"). That number wins
  over the PGN's Elo header. Ratings in the header are often misleading:
  a correspondence or daily rating over a dozen games can sit 300-400
  points below the player's real strength.
- **Anybody else's game**: read `WhiteElo`/`BlackElo` for the side being
  reviewed and calibrate to that. If the tag is missing, or the rating is
  provisional (RD > 150, or a handful of games), ask the user instead of
  assuming a low number.

Write the result into `annotations.json` as a top-level
`"audience": {"level": 1800, "source": "user-set"}` so the
brief-comment pass, the plan pause, the verifier and stage 3's narration