wordle/_bmad-output/implementation-artifacts/2-1-solver-script-word-ranking.md

Story 2.1: Solver Script & Word Ranking

Status: ready-for-dev

Story

As a developer, I want a solver script that pre-computes attempt counts for every target word using multiple algorithms, So that word difficulty scores are data-driven, not manual estimates.

Acceptance Criteria

1. Multi-algorithm solver: Given the solver script runs against the word bank, when it processes each target word with at least two solving algorithms, then it records attempt counts and computes an aggregated difficulty score per word.

2. Writes updated word bank: Given the solver completes, when it writes data/word-bank.json, then every target has a real difficulty value replacing the default 3.0.

3. Removes unsolvable words: Given a word is not solvable within 6 attempts by any algorithm, when the solver processes it, then that word is flagged or removed from the target set.

4. Shared types: Given the solver is TypeScript, when it imports types from shared/, then it uses the same WordBank and TargetWord interfaces as the server.

Tasks / Subtasks

• [ ] Task 1: Initialize solver package (AC: 4)

  • Create solver/package.json with TypeScript + tsx + @wordle/shared dependency
  • Create solver/tsconfig.json
  • Add solver to root workspace

• [ ] Task 2: Implement solver algorithms (AC: 1, 3)

  • Create solver/src/index.ts — orchestrates solvers, aggregates results, writes output
  • Create solver/src/entropy.ts — entropy/information-theory based solver
  • Create solver/src/minimax.ts — minimax or alternative solver

• [ ] Task 3: Test and run solver (AC: 2)

  • Run solver against data/word-bank.json
  • Verify difficulty scores are populated (not all 3.0)
  • Verify no unsolvable words remain in targets

Dev Notes

Solver Algorithm: Entropy-Based

1. Start with all target words as candidates
2. For each possible guess, compute expected information gain (how many candidates each feedback pattern eliminates)
3. Pick the guess with highest entropy
4. Filter candidates based on feedback
5. Repeat until solved or out of attempts

Solver Algorithm: Minimax

1. Start with all target words as candidates
2. For each guess, compute the worst-case candidate-elimination count
3. Pick the guess that minimizes the worst case (minimax)
4. Filter, repeat

Difficulty Score

difficulty = (entropyAttempts + minimaxAttempts) / 2

Files to Create

• solver/package.json, solver/tsconfig.json
• solver/src/index.ts, solver/src/entropy.ts, solver/src/minimax.ts
• Update root package.json to add solver workspace

References

• [Source: _bmad-output/planning-artifacts/prds/prd-wordle-2026-07-07/prd.md#FR-16, FR-17]
• [Source: _bmad-output/planning-artifacts/architecture/architecture-wordle-2026-07-07/ARCHITECTURE-SPINE.md]
• [Source: _bmad-output/planning-artifacts/epics.md#Epic 2]