菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.
Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.
Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.
Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.
Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.
Use when deploying HEATER App B, changing Railway or Vercel env vars/service config, diagnosing live 502s/timeouts/blank data after deploy, operating the Yahoo-token or Statcast relays, or driving Railway/Vercel headlessly from a terminal.
基于 SOC 职业分类
| 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. |
Most "bugs" in App B are environment/data divergence, not logic. Establish WHICH world is broken before touching code.
| 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().
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().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).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.?state=loading|error|empty isolates render vs data.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.
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?"
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.