OpenSkill Migration - Task 3 Complete ✅

Date: July 13, 2026
Status: User-facing documentation fully updated. Ready for deployment.

Summary

Task 3 (User-Facing Documentation Updates) is now complete. All documentation has been updated to reflect the OpenSkill rating system and TEI Grade presentation layer.

What Was Updated

RULES.md Section VIII ✅

  • Lexicon table: Added TEI Grade (E/V/C/I/P) and TEI Score (0-99) definitions
  • “Fixed opponent reference ratings”: Removed specific TEI numbers (1000/1200/1400), replaced with qualitative descriptions (Conservative baseline / Competent player / Sharp strategist)
  • “How your TEI moves”: Complete rewrite
    • Removed: Elo update formulas, K-factor table
    • Added: OpenSkill Bayesian system (μ, σ)
    • Added: Confidence evolution path (P→I→C→V→E with match count thresholds)
    • Added: Explanation of grade vs score
  • “After the sector”: Added grade display examples (V67, C42, I35, P28)
  • “Starting TEI”: Changed from “TEI 1000” to “P25 (Provisional grade, mid-range skill estimate)”

RULES.tex Section VIII ✅

All changes from RULES.md mirrored in LaTeX format:

  • Lexicon table updated
  • Reference ratings table updated (removed specific numbers)
  • “How your TEI moves” section completely rewritten
  • “After the sector” section expanded with grade examples
  • “Starting TEI” updated to P25 default

Verification ✅

  • No old Elo references remaining: grep confirms 0 matches for “Elo”, “K-factor”, “TEI 1000”, “TEI 1200”, “TEI 1400” in both files
  • Consistent terminology: Both RULES.md and RULES.tex use same OpenSkill terminology
  • Grade system documented: E/V/C/I/P grades fully explained with confidence thresholds

What’s Ready for Deployment

Backend ✅

  • OpenSkill rating engine (62 tests passing)
  • Cloud Functions updated (10+ files)
  • TEI Grade system (getTeiDisplay, getTeiGrade, getTeiScore)
  • Firestore schema updated (humanRating, groupRating with mu/sigma)
  • Certificate builder updated

Frontend ✅

  • Client services updated (stats-service.ts, game-service.ts)
  • Leaderboard updated for OpenSkill (schema.ts, leaderboard-service.ts)
  • Client-side preview (buildHumanSectorRankTable, applyHumanTeiSelfUpdate)
  • UI components (TeiDisplay, TeiChange, TeiGradeBadge)
  • Profile page updated

Documentation ✅

  • RULES.md Section VIII (user-facing rules)
  • RULES.tex Section VIII (LaTeX version)
  • OPENSKILL-ZETA-TODO.md (tracking document)
  • TEI-UI-DESIGN-GUIDE.md (design philosophy)

Tests ✅

  • All 822 tests passing (last known status)
  • 62 rating tests passing
  • 238 client tests passing (8 skipped)

Optional Post-Deployment Enhancements

These are not blockers, but nice-to-haves:

  1. In-game HUD grade badges — Show compact grade indicators during live play
  2. Leaderboard advanced view — Toggle to show raw μ/σ for power users
  3. Settings toggle — “Show Advanced Rating Stats” preference
  4. Accessibility audit — Verify grade colors meet WCAG AA, screen reader support
  5. UI search for hardcoded TEI numbers — Audit .tsx files for any remaining “1450” examples

Deploy Commands

When ready to deploy:

# Build everything
yarn build:all

# Build leaderboard SPA
yarn build:all:hosting

# Deploy to Firebase
yarn deploy:firebase

# Or deploy incrementally:
yarn deploy:functions    # Cloud Functions only
yarn deploy:firestore    # Firestore rules only
yarn deploy:hosting      # Static site only

What Changed From Elo to OpenSkill

Technical Changes

  • Rating model: Elo (single number) → OpenSkill (μ, σ tuple)
  • Update algorithm: Pairwise Elo with K-factors → Bayesian inference with uncertainty decay
  • Display: Raw TEI number (1450) → TEI Grade (V67)
  • Confidence tracking: K-factor stages → Continuous σ decay

User-Facing Changes

  • Grade letters: E/V/C/I/P show rating confidence (how certain we are)
  • Score numbers: 0-99 show skill estimate (how well you play)
  • Dual progression: Players now grind both letter AND number
  • Module experimentation feedback: Trying new modules spikes σ → grade drops temporarily
  • Conservative display: Uses μ - 3σ (conservative estimate) instead of raw μ

Benefits

  • Better matchmaking: OpenSkill handles team play (Module Zeta ready)
  • More accurate ratings: Bayesian inference converges faster than Elo
  • Gamified progression: Grade system creates visible milestones
  • Prevents rating inflation: Conservative estimate (μ - 3σ) keeps new players realistic
  • Module balance feedback: σ spike when trying new strategies is now visible

Notes

  • No backward compatibility needed: User confirmed safe to wipe Firebase, no production users
  • TEI branding preserved: “TEI” remains the brand name, OpenSkill is implementation detail
  • Design philosophy: “TEI Primary, OpenSkill in Tooltips” (show grades in UI, μ/σ in tooltips)
  • Module Epsilon fixed: Can now run W15+ games with drafting (separate task)

Next Steps

  1. Final testing: Run full test suite one more time before deploy
  2. Firebase wipe: Clear existing data (already confirmed safe)
  3. Deploy: Use commands above
  4. Monitor: Watch Cloud Functions logs for any rating calculation errors
  5. User communication: Update any external documentation (Discord, social media) about new grade system

Task Status: ✅ COMPLETE
Blocking Issues: None
Ready to Deploy: Yes

Warp 12 — a Double-Twelve domino variant for the NX Epoch.