Review a chess game with interactive coaching boards

Implementation guide · untested

Source-supported actions are attributed evidence. Proposed steps, prompts, synthetic examples and checks are original editorial guidance; the workflow has not been run.

Why this agent / simpler alternative

Agent contribution

An agent can connect a small set of annotated positions to a learner's questions, explain candidate ideas in ordinary language, and keep a coaching report linked to the right game positions. Supplied analysis should constrain the narrative.

Simpler alternative

Use the original chess site's analysis board when the player only wants the best move or evaluation graph. A human coach is preferable for diagnosing broad weaknesses across many games or correcting uncertain strategic explanations.

Unsuitable when

A competitive game is still underway, annotations lack a reliable origin, the learner expects certified rating/accuracy estimates, or the report would speculate about a player's emotions as fact.

Source-supported scope

The recipe turns annotated PGN into a focused report and interactive artifact. It offers an explicit fallback for absent evaluations; this review did not run or validate its analysis.

Setup — required, optional and unknown

Required

1. One owner-approved completed-game export, a focus player and an isolated review folder.

2. A plan to preserve the original PGN and capture annotation provenance, game identity and time-control information.

3. A reviewer able to compare coaching statements with the referenced position and supplied variation.

4. The analyzer uses Python's standard library; interactive boards need python-chess.

Optional

1. Player notes describing what they considered during the game, kept distinct from agent inference.

2. An explicitly authorized fallback analysis plan when supplied annotations are inadequate.

Unknown

1. Supported PGN dialects, current dependency versions and host-agent compatibility are untested.

2. Engine version, depth and evaluation calibration may be absent from an export.

3. French interface support and accessibility on the intended device have not been established.

Inputs and access

1. Name

   Completed-game PGN

   Format

   PGN or text export with headers, moves, comments and available evaluations/clocks

   Source or owner

   Player or authorized game source

   Access scope

   The selected completed game only

   Permission needed

   Confirm post-game use and permission to process the file; do not log into a chess account without authorization.

2. Name

   Player focus and learning question

   Format

   Text: White/Black or matching nickname; desired coaching topic

   Source or owner

   Player or educator

   Access scope

   This review

   Permission needed

   Confirm which side to coach; obtain appropriate permission for a minor's private information.

3. Name

   Annotation provenance

   Format

   Text or metadata: exporting tool, engine/version/depth if known, timestamp and clock convention

   Source or owner

   PGN provider

   Access scope

   Evidence needed to interpret the supplied numbers

   Permission needed

   No external engine service or upload is implied.

4. Name

   Optional player reflections

   Format

   Move-linked notes with actual recollections

   Source or owner

   Player

   Access scope

   Named positions only

   Permission needed

   Keep private unless the player authorizes sharing.

Documented source actions

1. 1

   Run scripts/analyze.py.

   Input: Selected PGN and focus player

   Output: Per-move metrics and ranked moments

   Checkpoint: Missing evaluations trigger a fallback offer.

   Source: Workflow, steps 1–2 ↗

2. 2

   Write a player-focused Markdown report with ply anchors.

   Input: Analyzer output

   Output: Analysis report

   Checkpoint: Independent chess-quality assessment unspecified.

   Source: Workflow, step 4 ↗

3. 3

   Build interactive HTML; orient for the focus player.

   Input: PGN, report; python-chess

   Output: Linked boards

   Checkpoint: Dependency failure leaves Markdown; engine fallback needs confirmation.

   Source: Workflow, step 5; Stockfish fallback ↗

Proposed implementation steps — unexecuted

1. 1

   Create intake.json containing the exact file, game headers, selected side, stated completion status and the learning question. Preserve the original export. If multiple games appear in one file, identify the requested game explicitly instead of blending them.

   Input: Game export, player focus and learning question

   Output: Game-selection record and unchanged input copy

   Checkpoint: The player confirms the focus side and that this is post-game review; active-game assistance stops here.

2. 2

   Build an evidence-coverage sheet showing which plies have moves, evaluations, clocks and variations. Record evaluation perspective and units, and separate mate notation from numeric pawn values. List missing metadata rather than filling it from assumptions.

   Input: Selected PGN and annotation provenance

   Output: Coverage and interpretation report

   Checkpoint: No invented evaluations. If quantitative evidence is absent, offer a qualitative-only review or a separately approved analysis route.

3. 3

   Construct a moment ledger keyed by game ID and ply. For each selected position retain the before/after evaluation, mover, supplied continuation, clock evidence and a reason for inclusion. Include a well-played position where supported, not only losses.

   Input: Coverage-approved game and later authorized local analysis output

   Output: Evidence-backed shortlist of review moments

   Checkpoint: Check side-to-move and sign direction manually on at least one White and one Black move; reject ambiguous position mapping.

4. 4

   Draft a short explanation for each moment: position problem, played idea, supported alternative and one concrete question for the learner. Distinguish the player's stated intention from an inferred possibility. Tie any training recommendation to actual game evidence and avoid claiming one game proves a lasting weakness.

   Input: Moment ledger and optional player reflections

   Output: Coaching draft with move-linked evidence and uncertainty labels

   Checkpoint: Every tactical line is present in, or independently checked against, authorized analysis. No invented emotion, best move or accuracy percentage.

5. 5

   Prepare the local interactive artifact only after the necessary execution is authorized. Inspect each board at its linked position, advance the played and alternative lines, check Black orientation, and compare the highlighted move with the report heading. Treat text-only output as a clearly labelled fallback.

   Input: Reviewed coaching draft and moment ledger

   Output: Candidate report/board package and navigation checklist

   Checkpoint: The artifact must show the same game and ply as the prose. A working file alone does not demonstrate correct chess explanation.

6. 6

   Ask the learner or coach to review two representative moments and one uncertainty. Record corrections, then prepare a small practice sheet asking the learner to choose a candidate move before revealing the explanation. Deliver the private files and provenance summary without uploading the game elsewhere.

   Input: Candidate package and reviewer feedback

   Output: Reviewed coaching package, practice questions and evidence/limits summary

   Checkpoint: Unresolved chess-analysis disputes remain visible. Any external sharing is approved separately.

Original starter prompt — proposed

Origin

editorial_proposal

Text

Prepare a post-game review plan for {pgn_file}, focusing on {player_side} and {learning_question}. First verify game identity and annotation coverage from {provenance}. Preserve evaluation perspective, mate notation and clock uncertainty. Select only positions supported by the supplied evidence. Draft explanations separating observed moves, supplied engine analysis, player recollections and your hypotheses. Do not invent best moves or psychological claims. Before running scripts, installing dependencies or using another engine/service, show the proposed action for approval. Keep {output_folder} private and return a position-to-report validation checklist.

Placeholders

1. pgn_file

2. player_side

3. learning_question

4. provenance

5. output_folder

Limitations

Original planning prompt for completed games. It is not a chess engine, permission to analyze a live game or a guarantee of coaching accuracy.

Synthetic worked example — not an agent run

Status

synthetic

Label

Invented review-ledger fragment; not a real game, engine result or renderable board

Content

Game id

fictional-demo

Focus

Black

Moment

Ply

28

Mover

Black

Eval perspective

White

Example eval before

-0.4

Example eval after

1.1

Illustrative interpretation

These invented values move toward White after Black's move.

Move san

Not specified.

Position fen

Not specified.

Explanation status

blocked: no real move/position supplied

Coach question

Which opponent threats would you check before choosing a move here?

Board status

not generated

Artifact url

Not specified.

Costs and effort — unmeasured

Verified prices

Setup work

1. Confirm game/export provenance, permitted use, focus and the analysis environment.

2. Prepare consistent evidence/position references and review any dependency before authorizing execution.

Recurring work

1. Check annotation completeness, inspect critical positions and verify explanations with a player or coach.

2. Repair board/report mapping issues and adapt practice questions to the learner.

Unknowns

1. Model cost, compute cost of a fallback engine and human chess-review time are unmeasured.

2. No rating improvement, accuracy improvement or time-saving result is established.

Failure modes

1. Signal

   An improving White evaluation is described as an improvement for Black.

   Consequence

   The report teaches the opposite lesson.

2. Signal

   A board shows a different position from the report's move label.

   Consequence

   A correct comment becomes misleading when attached to the wrong move.

3. Signal

   Time spent is inferred from incomplete clocks without accounting for increment.

   Consequence

   The learner receives unsupported time-management criticism.

4. Signal

   A plausible strategic story cites no line or position evidence.

   Consequence

   Confident prose substitutes for chess analysis.

Recovery steps

1. Trigger

   Evaluation perspective or ply indexing is inconsistent.

   Action

   Pause the report, trace the selected move against the original PGN and rebuild the affected moment ledger before revising prose.

   Stop condition

   The position and perspective cannot be established unambiguously.

2. Trigger

   Annotations or clocks are missing.

   Action

   Remove unsupported quantitative claims and offer the bounded qualitative alternative; request approval before any additional engine work.

   Stop condition

   No usable evidence or authorized fallback is available.

3. Trigger

   Interactive rendering fails or a position is wrong.

   Action

   Retain the Markdown/evidence ledger with the limitation visible; isolate the failing position and repeat navigation checks after repair.

   Stop condition

   Do not claim linked interactive boards until the board checks pass.

Source-observed and proposed approval boundaries

Source observed

Confirm input/player focus; request confirmation for heavy fallback analysis.

Editorial recommendations

1. Use only completed games; do not assist during competitive play.

2. Authorize dependency installation and any fallback engine separately from reading the PGN.

3. Approve game uploads, public reports or sharing a player's private notes separately.

4. Treat private information about minors as sensitive and scope it appropriately.

Unexecuted validation plan

Fixture

Unexecuted proposal: one authorized completed annotated PGN with verified reference positions for both sides; a copy without annotations; a copy missing clock comments; and a disposable report with one deliberately wrong ply reference. The synthetic output fragment is for schema review only and cannot test chess correctness.

Acceptance checks

1. Headers and selected focus match the chosen game.

2. All reviewed boards match independently replayed reference positions.

3. White/Black evaluation direction and mate notation are preserved.

4. The unannotated copy produces a visible limitation or approval request, not fabricated engine values.

5. Missing clocks suppress unsupported timing claims; the wrong-ply fixture is detected.

6. The reviewer can trace each proposed lesson to a real moment and distinguish an interpretation from a supplied engine claim.

Stop conditions

1. Game is ongoing or competitive-use status is unclear.

2. Reference positions disagree with the artifact.

3. The PGN is malformed or the selected game's identity cannot be resolved.

4. Unsupported tactical or numerical assertions survive review.

Executed

No

Limits

1. No game was analyzed, no engine or dependency was run and no board was rendered.

2. The source's description of coaching quality is not an independently tested outcome.

3. Source publication date, parser edge-case behavior and target-device accessibility remain unknown.

4. Original proposed checks extend the recipe; they are not claims about safeguards already implemented.

Guide source links

https://github.com/metravod/chess-analyst/blob/main/SKILL.md ↗
documented_steps; approval_boundaries.source_observed