heater-appb-debugging

name	heater-appb-debugging
description	Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.

App B Debugging Playbook — live vs local divergence first

Most "bugs" in App B are environment/data divergence, not logic. Establish WHICH world is broken before touching code.

Step 0 — know the worlds

Axis	Local dev	Railway App B
Yahoo league tables	usually EMPTY (rosters/matchups) → FA/team/matchup surfaces degrade honestly	live via token relay
FanGraphs	reachable	403 (datacenter IP) → Marcel-fallback projections
Statcast xwOBA	via local fetch	only via Statcast relay env
DB	your 26MB data/draft_tool.db	container DB, REBUILT by bootstrap each deploy (~10 min warm-up)
git worktrees / CI	fresh EMPTY draft_tool.db — a query returning 0 rows there is expected, not a bug	—

So: "value=0 / empty board on live only" → suspect data source (403, relay, bootstrap still warming), not code. "Works live, empty locally" → your Yahoo tables are empty; either accept the honest-empty or sync once via try_reconnect_yahoo().sync_to_db().

Step 1 — read the state, not the symptom

• python -c "from src.database import get_refresh_log_snapshot; import json; print(json.dumps(get_refresh_log_snapshot(), indent=2))" — per-source status/tier/age. partial/cached/skipped are honest states, not failures.
• python scripts/diag_live_accuracy.py (local): identity corruption, probables, projection volumes.
• python scripts/diag_matchup_truth.py --api-base https://heater-v1-0-1.vercel.app --token <clerk-jwt> (live vs Yahoo truth). Get the JWT from the signed-in browser console: await window.Clerk.session.getToken().
• Railway logs via the GraphQL helper (see heater-appb-deploy-ops). Note: App B's api.* INFO logs are hard to read there — prefer local repro or debug-via-response (add a reason/detail field to the contract; that's how the WS4 empty-trades class was made greppable).

Step 2 — reproduce at the right layer

• Run the API locally against your real DB: uvicorn api.main:create_app --factory --port 8000 (it's a FACTORY — plain api.main:app fails) + the heater-web-live preview config, NEXT_PUBLIC_HEATER_LIVE=1.
• Endpoint-level: hit the service method directly in a REPL with the real pool — fake-service tests can't see engine-shape mismatches (the daily-mode "" matchup / {} urgency bugs were invisible to green synthetic tests).
• Frontend: usePageData dev override ?state=loading|error|empty isolates render vs data.

Step 3 — check the known bug classes before inventing a new one

ET-date skew (evening-ET wrongness → src/et_today.py); NaN leakage ("nan" badges); key-casing/unit mismatches at the engine seam (heater-appb-engine-composition); identity joins by name (heater-appb-player-identity); dormancy predicate flipped (401s = CLERK_ISSUER set?); Known Design Choices (heater-appb-known-non-bugs) — confirm a match and move on.

Failure story — fix the data model, not the symptom

Matchup rank columns showed scrubs/"Test Pitcher" outranking stars. The tempting fix was tweaking rank math; the actual root was ranking over the full ~9,888-row pool (minor leaguers + fixtures). Fix: player_rankings.fantasy_relevant_pool gate (85a340c), math untouched. Corollary: the live "FA value=0" (M-1) root was FanGraphs 403, fixed by the Marcel fallback — not by touching valuation. Ask "what data did this code actually receive?" before "what's wrong with this code?"

When NOT to apply

Clean test failures with a clear diff — just fix them (heater-appb-testing-ci for harness quirks). True deploy/infra outages (502s, env) → heater-appb-deploy-ops.