README Todo list and CLAUDE.md architecture section are stale post-redesign #7

New Issue

2026-08-04T18:54:59Z

logaritmisk commented

2026-08-04 18:54:59 +00:00

Both docs still describe the pre-redesign engine. They were written before T0–T4 and never pruned, so they now actively mislead — the CLAUDE.md architecture section in particular is what a fresh Claude Code session reads first.

README Todo list

Item	Reality
"Time needs to be an enum so we can have multiple states (see `batch::compute_elapsed()`)"	Superseded. `Time` is a trait — `src/time.rs:11`, `pub trait Time: Copy + Ord + Send + Sync + 'static`, with `Untimed` as a built-in impl. `batch.rs` no longer exists.
"Add Observer (see argmin for inspiration)"	Done. `src/observer.rs:13`, `pub trait Observer<T: Time>: Send + Sync`, plus `NullObserver`.
"Add examples (use same TrueSkillThroughTime.(py\|jl))"	Done. `examples/atp.rs`, `examples/scored.rs`, `examples/atp.csv`.
"Benchmark `Batch::iteration()`"	Type is gone; the bench survives as `benches/batch.rs`. Needs renaming or closing.
"Add tests for `quality()` (use sublee/trueskill as reference)"	Partially done — `src/lib.rs:273 test_quality` and `tests/api_shape.rs:195 predict_quality_two_teams` exist, but neither is cross-checked against sublee/trueskill. Genuinely still open; keep it.

CLAUDE.md architecture section

The documented data flow is History → Batch[] → Game[] → teams/players. Four of the modules it describes no longer exist:

batch.rs / Batch — replaced by src/time_slice.rs / TimeSlice
agent.rs / Agent — replaced by src/competitor.rs / Competitor + src/storage/skill_store.rs
player.rs / Player — replaced by Competitor + src/drift.rs (Drift / ConstantDrift)
message.rs / TeamMessage / DiffMessage — replaced by src/factor/ (team_sum.rs, rank_diff.rs, trunc.rs, margin.rs) over VarStore

Undocumented but load-bearing: src/schedule.rs, src/convergence.rs, src/color_group.rs, src/key_table.rs, src/arena.rs, src/storage/, src/event_builder.rs, src/outcome.rs, src/rating.rs.

The stated public API (Game, Gaussian, History, Player) is also wrong — see src/lib.rs:32-47 for the actual export list.

The closing note "time in History/Batch is currently an f64; the README notes it needs to become an enum" is doubly stale and should go.

Scope

Prune the resolved README Todo items; keep the quality()-vs-sublee one; either rename or drop the Batch::iteration() bench item.
Rewrite the CLAUDE.md architecture section against the current src/ layout, including the modules added by T2–T4.
No code changes.

Both docs still describe the pre-redesign engine. They were written before T0–T4 and never pruned, so they now actively mislead — the CLAUDE.md architecture section in particular is what a fresh Claude Code session reads first. ## README Todo list | Item | Reality | |---|---| | "Time needs to be an enum so we can have multiple states (see `batch::compute_elapsed()`)" | Superseded. `Time` is a trait — `src/time.rs:11`, `pub trait Time: Copy + Ord + Send + Sync + 'static`, with `Untimed` as a built-in impl. `batch.rs` no longer exists. | | "Add Observer (see argmin for inspiration)" | Done. `src/observer.rs:13`, `pub trait Observer<T: Time>: Send + Sync`, plus `NullObserver`. | | "Add examples (use same TrueSkillThroughTime.(py\|jl))" | Done. `examples/atp.rs`, `examples/scored.rs`, `examples/atp.csv`. | | "Benchmark `Batch::iteration()`" | Type is gone; the bench survives as `benches/batch.rs`. Needs renaming or closing. | | "Add tests for `quality()` (use sublee/trueskill as reference)" | Partially done — `src/lib.rs:273 test_quality` and `tests/api_shape.rs:195 predict_quality_two_teams` exist, but neither is cross-checked against sublee/trueskill. Genuinely still open; keep it. | ## CLAUDE.md architecture section The documented data flow is `History → Batch[] → Game[] → teams/players`. Four of the modules it describes no longer exist: - `batch.rs` / `Batch` — replaced by `src/time_slice.rs` / `TimeSlice` - `agent.rs` / `Agent` — replaced by `src/competitor.rs` / `Competitor` + `src/storage/skill_store.rs` - `player.rs` / `Player` — replaced by `Competitor` + `src/drift.rs` (`Drift` / `ConstantDrift`) - `message.rs` / `TeamMessage` / `DiffMessage` — replaced by `src/factor/` (`team_sum.rs`, `rank_diff.rs`, `trunc.rs`, `margin.rs`) over `VarStore` Undocumented but load-bearing: `src/schedule.rs`, `src/convergence.rs`, `src/color_group.rs`, `src/key_table.rs`, `src/arena.rs`, `src/storage/`, `src/event_builder.rs`, `src/outcome.rs`, `src/rating.rs`. The stated public API (`Game`, `Gaussian`, `History`, `Player`) is also wrong — see `src/lib.rs:32-47` for the actual export list. The closing note "`time` in `History`/`Batch` is currently an `f64`; the README notes it needs to become an enum" is doubly stale and should go. ## Scope - Prune the resolved README Todo items; keep the `quality()`-vs-sublee one; either rename or drop the `Batch::iteration()` bench item. - Rewrite the CLAUDE.md architecture section against the current `src/` layout, including the modules added by T2–T4. - No code changes.

logaritmisk referenced this issue

2026-08-04 19:14:46 +00:00

`quality()` and `predict_quality()` panic for anything other than exactly 2 rating groups #9

logaritmisk commented

2026-08-04 20:12:26 +00:00

Done in 9e8515b.

CLAUDE.md's architecture section is rewritten against the current src/ layout — the data flow, the modules that replaced Batch/Agent/Player/message.rs, the previously undocumented ones (schedule, convergence, color_group, key_table, arena, storage, event_builder, outcome, rating), and the real export list. It also now records the invariants that are easy to violate: ties needing a positive p_draw, NaN never counting as convergence, log-space evidence, color contiguity, forbid(unsafe_code), and ingestion-order equivalence — plus a note that some goldens are convergence residuals rather than exact values, which cost me time to work out during this branch.

The README Todo list lost five entries that were already done, including the "Time needs to be an enum" item — Time has been a trait since T2 and the batch::compute_elapsed() it pointed at no longer exists. The quality()-vs-sublee cross-check stays open, and is now the only remaining item; see #9.

Done in 9e8515b. `CLAUDE.md`'s architecture section is rewritten against the current `src/` layout — the data flow, the modules that replaced `Batch`/`Agent`/`Player`/`message.rs`, the previously undocumented ones (`schedule`, `convergence`, `color_group`, `key_table`, `arena`, `storage`, `event_builder`, `outcome`, `rating`), and the real export list. It also now records the invariants that are easy to violate: ties needing a positive `p_draw`, NaN never counting as convergence, log-space evidence, color contiguity, `forbid(unsafe_code)`, and ingestion-order equivalence — plus a note that some goldens are convergence residuals rather than exact values, which cost me time to work out during this branch. The README Todo list lost five entries that were already done, including the "Time needs to be an enum" item — `Time` has been a trait since T2 and the `batch::compute_elapsed()` it pointed at no longer exists. The `quality()`-vs-sublee cross-check stays open, and is now the only remaining item; see #9.

logaritmisk closed this issue

2026-08-04 20:13:51 +00:00

logaritmisk added the docs label 2026-09-07 13:53:06 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: logaritmisk/trueskill-tt#7