review-rubric.md 5.5 KB
Architecture Spine Review — Rubric Checklist
Reviewed: ARCHITECTURE-SPINE.md (feature altitude, Wordle Clone v1)
Date: 2026-07-07
Verdict: PASS — No blocking gaps. Two low-severity observations.
Checklist Results
1. It fixes the real divergence points for the level below and misses none — PASS
All major architectural divergence points at feature altitude are addressed by ADs:
| Divergence risk | Addressed by |
|---|---|
| Server stores session/game state | AD-1 (stateless) |
| Daily word requires DB/cron | AD-2 (deterministic formula) |
| Multi-language drift, duplicate types | AD-3 (TypeScript everywhere) |
| Word bank needs database | AD-4 (static JSON) |
| Word bank leaks to client | AD-5 (server-side validation) |
| Feedback computed inconsistently | AD-6 (server-side scoring) |
| Server tracks game progress | AD-7 (client owns state) |
| Monorepo package boundary violations | AD-9 (shared types) |
No missing divergence points for this altitude and project stakes. The solver-is-offline boundary is stated in the design paradigm but has no separate AD — see Finding #2 below.
2. Every AD's Rule is enforceable and actually prevents its stated divergence — PASS
All 9 ADs carry rules that are specific enough to enforce via code review:
- AD-1: "server stores nothing between requests" — verifiable via absence of session/memory stores.
- AD-2: Explicit formula with timezone — verifiable via unit test.
- AD-3: "no package defines its own copy of a shared type" — verifiable via grep/import analysis.
- AD-4 through AD-9 are similarly concrete and testable.
3. Nothing under Deferred could let two units diverge — PASS
All 7 deferred items are either:
- Bounded by an invariant interface (solver algorithms → solver package interface; word bank source →
WordBankinterface; skill metric →skillMetricnumber in API contract). - Owned by a different layer (deployment mechanism, HTTPS/TLS — deployment environment; npm workspace — tooling).
- Post-v1 (hints on attempts 5-6).
The invariant interfaces are sufficient to prevent divergence for a single-developer hobby project.
4. Named tech is verified-current — PASS
| Tech | Spine version | Verified current (July 2026) |
|---|---|---|
| TypeScript | ^5.x | Yes |
| Node.js | ^22 LTS | Yes |
| React | ^19.x | Yes |
| Vite | ^6.x | Yes |
| Express | ^5.x | Yes |
5. If a spec drove it, it covers that spec's capabilities — PASS
The PRD (prd-wordle-2026-07-07/prd.md) is listed as the source. All 19 FRs and all 5 UJs are traced in the Capability -> Architecture Map. Every FR has:
- A location in the structural seed.
- A governing AD (except FR-16, which is an offline script under the solver package — no runtime AD needed).
No PRD capability is unaddressed or ambiguously assigned.
6. Every dimension the altitude owns is decided, deferred, or an open question — PASS
All decisions at feature altitude are covered:
- Decided: paradigm (SPA + stateless REST), language (TypeScript), runtime (Node/React/Express/Vite), data storage (static JSON + localStorage), API design (REST endpoints), code organization (monorepo), client/server boundary, daily word mechanism, Play Again mechanism, feedback algorithm.
- Deferred: deployment mechanism, HTTPS/TLS, solver algorithm selection, skill metric formula, word bank source.
- Open questions: None left dangling — the PRD's 4 open questions are all reflected in Deferred.
The operational/environmental envelope is appropriately deferred for a hobby project: "Deployment mechanism — how the server process is started, restarted, proxied" is explicitly deferred to the deployment environment. No enterprise concerns (SLAs, HA, monitoring) are missing given the calibrated stakes.
Findings
Finding #1 (Low) — AD-8 over-specifies the sampling distribution
AD-8 mandates "Gaussian sampling" (normal distribution centered on skill metric). The PRD (FR-11) only requires "selected randomly from the word bank with weighting based on the player's skill level" — it does not prescribe a specific distribution. Gaussian is a valid implementation of "weighting," but the AD narrows the design space beyond what the PRD requires. This is not wrong (architecture refines PRD), but it is more opinionated than necessary at this altitude.
Recommendation: Consider softening to "weighted random selection based on skill metric" and leaving the specific distribution to implementation, consistent with the deferred "skill metric formula" item.
Finding #2 (Observation) — Solver-as-offline has no governing AD
The structural seed and design paradigm text correctly position the solver as "an offline script, not part of the runtime." However, FR-16 (Multi-algorithm solver) shows no governing AD in the Capability -> Architecture Map. All other FRs are assigned to one or more ADs. This is not a real gap — the paradigm statement and structural seed make the boundary clear — but the traceability table has a small inconsistency.
Recommendation: Either add a brief AD (e.g., "AD-10 — Solver is offline pre-compute; its output is consumed as static data at server start") or note in the map that the solver's output is governed by AD-4.
Summary
The spine is well-constructed for a hobby/learning project at feature altitude. All 9 ADs are specific, enforceable, and address real divergence points. Traceability to the PRD is exhaustive. Deferred items are appropriately bounded by invariant interfaces. The two findings above are minor and do not block proceeding to epics/stories.