WhyThisMove: building an AI chess coach that explains mistakes

The gap

Most chess tools can tell a player that a move is bad. Fewer tools explain why the move felt natural, what idea it missed, and how a human should think differently the next time.

That gap is the reason I started building WhyThisMove, also called IronWall Chess Engine in my portfolio notes. The product is not meant to replace a chess engine. Stockfish already calculates better than almost every human. The product is meant to sit between a strong engine and a learner who needs language, context, pattern recognition, and practice.

The core question is simple:

How can an AI coach turn best-move output into a human learning loop?

Status and evidence

This is a private testing project, so this note focuses on the product reasoning and architecture rather than publishing the full app surface. The public evidence trail lives in the project evidence page, while the actual product work covers frontend, backend, chess analysis, LLM orchestration, deployment, and tests.

That status matters. I do not want the site to pretend every private product is a public launch. A private testing project can still be useful evidence if the write-up is specific about the problem, the system shape, and the engineering tradeoffs.

The shape of the product

The product combines several pieces:

• Stockfish for tactical and positional engine analysis
• Maia-style human move analysis for understanding likely human mistakes
• Opening training for repeatable pattern practice
• Blunder training for focused correction
• Game review for turning full games into lessons
• LLM explanations for natural-language coaching

The important part is not that each module exists. The important part is the order in which the product explains a position.

A beginner does not need a long engine line first. A beginner needs to know the idea. A stronger club player might need the candidate moves, missed threat, and why the engine's first choice is robust. That means the coaching layer has to translate the same board state into different levels of explanation.

Why a plain engine wrapper is not enough

The easiest version of this product would be:

1. Send a FEN position to Stockfish.
2. Get the best move and evaluation.
3. Ask an LLM to explain it.

That is useful for a demo, but weak as a product.

The problem is that a chess engine is optimized for accuracy, while a coach is optimized for learning. The engine can say a move wins 1.3 pawns. A learner often needs to know that a knight was overloaded, a pawn break changed the center, or a quiet defensive move removed counterplay.

So the system has to preserve engine accuracy while adding teaching structure. The LLM should not freely invent chess truth. It should receive constrained context: candidate moves, eval changes, principal variation, tactical motifs, opening phase, and the learner's actual mistake.

Product architecture

The current stack reflects that split:

• React, Vite, TypeScript, Mantine, Tailwind for the app interface
• Zustand and TanStack Query for local state and server interaction
• FastAPI for backend routes
• PostgreSQL and ClickHouse for product and event data
• Stockfish and Maia-oriented analysis for chess intelligence
• OpenRouter LLM calls for explanations
• Docker Compose and Caddy for deployment structure
• Vitest, Testing Library, and Playwright for checks

This is a product where testing matters because the UI can look fine while the learning loop is broken. A good test is not only whether the board renders. A good test checks whether a position review creates the expected sequence: board state, engine result, explanation, practice prompt, and next action.

What I would show in an interview

If I had to explain this project quickly, I would not start with the UI. I would start with the product loop:

1. import or create a chess position
2. analyze the position with engine context
3. compare the user's move with stronger candidate moves
4. explain the mistake in human language
5. turn the mistake into a small practice task

That loop is the product. The board, account system, database, and deployment are all there to make the loop reliable.

The hardest design choice

The hardest design choice is deciding how much certainty the product should express.

Chess engines can be precise, but explanations can become too confident. A move can be bad for tactical reasons in one line and strategically awkward in another. A learner might also need a simpler explanation than the deepest truth of the position.

So the writing style of the coach matters. It should prefer:

• This move weakens...
• The main issue is...
• A useful way to see the position is...
• The engine prefers... because...

It should avoid pretending that every position has a single clean moral.

Next version

The next version I would push hardest on is personalization. A beginner, an intermediate player, and a stronger club player should not receive the same explanation. The same engine line can become:

• a one-sentence tactical warning
• a three-step positional explanation
• a candidate-move comparison
• a practice drill based on the repeated mistake

That is where the product becomes more than an engine narrator. It becomes a coach that remembers what the learner tends to miss.

What I learned

Building this product taught me that AI products are often translation systems.

The raw intelligence is not enough. The product has to translate from engine language to learner language, from analysis to practice, and from a one-time answer to a repeatable habit.

That is also why the project belongs on this site. It is not only portfolio evidence. It is a record of a product question I care about: how to make strong computation useful to normal people.