# 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]