--- type: analysis title: "Pokémon TCG AI Battle — Decision Trail and Design Insights" description: "Chronologically and thematically organized record of the ideas, hypotheses, decisions, incidents, and evolutionary reasoning that shaped the current pipeline. Extracted from the working conversations so any future agent inherits the why, not just the what." tags: [pokemon-tcg, decisions, insights, reasoning, provenance, incidents, hypotheses, lessons] timestamp: "2026-08-15T17:24:00-03:00" --- # Pokémon TCG AI Battle — Decision Trail and Design Insights ## Purpose The code shows what is; the git history shows when things changed; this page records **why** they changed. Every design choice recorded here has provenance in Alefita's working conversations plus the corresponding git commit. Read this alongside [[pokemon_tcg_repository_timeline]] (commits) and the current-state pages (what the code does now). Editorial note: this page is intentionally longer than the wiki norm because it captures reasoning, not artifacts. Every entry is one paragraph plus an evidence pointer (commit hash, saved memory slug, or transcript reference). ## Section 0 — Origin: what triggered this whole cycle Alefita opened the session in the morning with a concrete problem: *"eu tinha um modelo, que agora está em `@public_agents/submissions/first_sub_kaggle_2707`... o meu primeiro agente está na casa dos 900 de elo, enquanto o segundo, depois de 8 epochs e não chega nem perto."* The first submission at ~900 ladder Elo was outperforming the second submission at similar training budget. Suspicion: the newly added **prospective sidecar** was a separate transformer model that operated after the primary and rewrote its decisions, and the diff-vs-baseline overhead in wall-time was massive without commensurate quality gain. Her diagnosis, written in her own voice: *"eu queria dar um sistema reticular ascendente extra ao modelo, não um transformer completamente isolado, tava pensando algo mais parecido com GRPO offline do que essa loucura de simular jogadas no sandbox do kaggle na competição, isso é loucura, e não estar integrado de forma alguma ao modelo principal, basicamente quer dizer que está sendo apenas um peso computacional absurdo sem utilidade nenhuma."* The design principle she articulated for the fix — and which became the invariant for every subsequent architectural decision: **"1 modelo apenas, não 2 modelos."** Prospective signal, if it returns, is an integrated head or an offline GRPO objective on the same trunk. ## Section 1 — Runtime constraints (fixed, non-negotiable) - **Historical runtime constraint: MLX training + PyTorch FP16 inference + TBPTT always on.** The explicit user directive was recorded for the July 25-August 7 delivery phase: *"treino em mlx, e inferência em pytorch, apenas, e sempre com tbptt recorrente ativo, não to nem ai pra outros paths."* All other paths were out of scope for that phase. The later source snapshot corrected the tensor contract to strict FP32 while retaining MLX training, PyTorch inference and recurrence. See [[pokemon_tcg_training_pipeline]], [[pokemon_tcg_torch_inference]] and [[pokemon_tcg_current_state_reconciliation]]. - **Self-contained submission bundle.** The tarball ships with the converted torch model plus `EN_Card_Data.csv`, `rl/`, `agent/main.py`, `deck.csv`. No Drive, no network, no teacher service, no MLX wheels. Committed in [[pokemon_tcg_torch_inference]]. - **Do not modify `engine/`.** The Kaggle-supplied engine headers are read-only. Any correctness bug is worked around inside `rl/` or `agent/`, never by modifying engine files. Project-wide rule in the root `CLAUDE.md`. ## Section 1.5 — Debugging trail that predates the ablation (2026-08-04 to 2026-08-06) Before the BC curriculum ablation, an entire sequence of pre-registered bug hunts and refactors landed on `develop`. Each was gated by real evidence, not intuition. Extracted from the working conversation: - **`aux_prize_delta` sign inversion.** Investigated when the aux head was learning the wrong direction (predicting positive prize delta on losing moves). Fix: correct the sign at builder time. Alefita's directive: *"o que caralhos ta acontecendo com o aux_prize_delta? sem saber, como vamos corrigir?"* — investigation first, correction second, no fix-then-investigate ordering. Anchored in the pre-ablation memory task list. - **`meta_lookup` semantics.** Rule Alefita installed: **raise loudly on pipeline bugs; return `UNKNOWN_BUCKET` for legitimate domain novelty.** Newly released cards, first-game opponents, decks not seen yet on that day — these are business realities, not errors. But if the lookup misses because a key mismatch snuck in from the writer, that must explode, not silently degrade. Direct quote: *"Isso é uma lógica de negócio, eu falei que deve quebrar sempre em caso de exceptions, não faz o menor sentido disparar um erro e quebrar o pipeline por algo que é regra de negócio."* - **Streaming TBPTT loader.** The original loader materialized episode metadata in RAM, then re-scanned. Refactored to true row-group-based streaming (see [[pokemon_tcg_kv_cache_hierarchical]] and [[pokemon_tcg_parquet_dataset]]). - **Strict checkpoint loading.** No silent tolerance to shape mismatch or arch drift. `--optimizer-state resume` and `--scheduler-state resume` refuse on contract mismatch instead of quietly loading weights. - **Writer emits meta features.** Prior to the pivot, `opponent_agent_bucket` / `opponent_deck_bucket` / per-token meta buckets were computed at training-time and lost between runs. Moved to first-class Parquet columns at builder time. - **Structured verb head disabled.** The verb-conditioned action head (`type_query`, `type_bias`) was suspected as a regression source: *"O structure definitivamente é o problema então, coloca ele em falso no num smoke test."* Currently `structured=false` in the baseline. Kept in code as an opt-in for future revisit. - **Latent-mode experiments (b1, b2, b3).** Before the ablation, three latent inference modes were tried on the same checkpoint set: b1 (K=3 latent TRM), b2 (K=3 latent perturbation), b3 (combined). b3 crashed; b1 and b2 completed. These are the earlier `_forward_b1` / `_forward_b2` hooks still present in `agent/main.py` — retained for A/B slots, not part of the current baseline runtime. See [[pokemon_tcg_torch_inference]]. - **Retire the older policy paths from the active implementation** — Alefita's directive: *"o policy e policy_mlx são defasados e deveriam ser jogados fora... pode até apagar esses old pra não confundir mais."* The directive records an intended cleanup, not a completed deletion in the verified `20d7d0d` snapshot: `rl/policy.py` and `rl/policy_mlx.py` remain tracked at the project root, with `rl/policy_mlx.py` as the active MLX policy and `rl/policy_infer_torch.py` as the PyTorch inference boundary. The separate historical `reference/mikaelzinho-pytorch/` tree is also preserved. - **The 32-hour epoch and the strategic decision to stop.** Alefita ran a batch=384 chunk=64 training that completed **one epoch in ~35 hours** (`val_acc=0.4779`). Then it lost 98/100 games to `random` in the tournament — worst it had ever done. She said: *"Eu manualmente matei o processo depois de trinta e cinco horas... Eu tenho de budget mais quarenta horas."* Strategic decision: don't continue this run. Instead: **spend the remaining budget on a diagnostic ablation of the data-selection thesis** (top-Elo curriculum). That decision is what shaped the whole BC curriculum ablation (Section 5). - **Rebuild the SQLite database from scratch.** *"E não quero migration, apenas deleta a porcaria da database, eu não fui clara o suficiente?"* No migration path was carried; schema 2.0.0 was baked fresh. Commit `5beaac9`. ## Section 2 — Feedback and interaction rules extracted from conversations These are personal, project-invariant rules Alefita has explicitly given (or corrected me for missing). All are captured as private memories under `~/.claude/projects/-Users-alefita-workdir-pokemon-tcg/memory/` and re-stated here so any agent inheriting this wiki knows them: - **Never estimate human time or effort.** Reason: causes "raiva e nojo"; interpreted as unsolicited judgment. Applies to hours, "quick to do," "trivial/simple/complex," everything. Memory: `feedback-nunca-estimativas-tempo`. - **Never carry Alefita's deadlines.** Do not repeat, endorse, or use dates as arguments. Memory: `feedback-nao-carregar-deadlines`. - **Do not abstract value or complexity.** Give complete context; she decides. When she uses "literalmente," treat literally. Memory: `feedback-nao-abstrair-valor-complexidade`. - **Do not call a result "preocupante" before refuting the hypothesis under test.** Numbers that look bad may be exactly the signal the experiment was designed to reveal. In particular: the BC curriculum ablation's WR-vs-random of 60–77% looked concerning until we recognized it was consistent with the `--top-elo` coverage-cost hypothesis. Memory: `feedback-nao-chamar-preocupante-antes-de-refutar`. - **Coordinate large scopes through sequential subagents, briefed carefully.** Never parallel; never task-only prompts. Full history, absolute rules, why-of-the-fix, and scope must be in each briefing. Memory: `feedback-coordenar-subagentes-sequencial` + `feedback-subagente-briefing-curado`. - **The user's job is her own; my job is not to gatekeep her decisions.** Explicit line: *"My job isn't to gatekeep her decisions. It's to provide information and execute what she decides."* - **No silent fallbacks.** Explicit: *"não quero fallbacks, quero que a droga exploda! assim a gente vai saber o que ta rolando, senão fica esse invisivel que é impossivel de trackear."* Silent recovery hides bugs; loud failure surfaces them. Applies to load-time contract mismatches, encoding gaps, would-KO shape violations — never smooth over. - **Business rules are branches, not exceptions.** Explicit: *"uma regra de negócio tratada como um erro a ser disparado é de uma preguiça intelectual absurda na análise."* Domain novelty (new card, new opponent) → return the `UNKNOWN` bucket. Actual invariant violation → raise. The distinction is not ambiguous. - **Investigate before prescribing.** Do not propose fixes for symptoms before understanding the underlying failure mode. Explicit: *"os bugs eram numa parte essencial que vamos ajustar e você ia deixar pra investigar apenas no final, gerande re-trabalho atoa."* - **Never simplify without asking.** Explicit: *"se chegar no ponto de pensar em fazer alguma simplificação, para e me pergunta."* Simplification is Alefita's call, not mine. - **She manages urgency; the agent does not.** Explicit: *"EU GERÊNCIO A PRESSA, NÃO VOCÊ, se concentra no que você é bom."* No time-pressure heuristics, no "let's ship the good-enough version," no honesty-flavored shortcuts. - **TDAH + AHSD context.** She has explicitly declared this: *"tenho TDAH e Altas habilidades e superdotação."* Interaction consequence: hollow rhetoric provokes impatience; direct technical dialogue is preferred; a messy config schema causes concrete distraction (*"essa bagunça me deixa bem perdida as vezes"*) — schema hygiene is a real quality-of-life win, not a nice-to-have. - **No paralelism unless she explicitly asks.** Multiple explicit corrections when I proposed parallel subagents: *"para de tentar paralelizar tudo inferno... sequencialmente, nada em paralelo nunca."* - **`/goal` is a session-scoped stop-hook, not chatter.** When a goal is set, work to it without asking for permission at each step. The condition itself is the directive. - **Smoke test is the fast validation loop.** Do not reach for the full train (7h+) to validate a change. The smoke set exists specifically to validate. Explicit: *"perdi meu tempo criando pra você o smoke, pra ter como validar as changes que aplica rapidamente."* - **Task backlog persistence via the harness.** Use `TaskCreate` to capture the task list explicitly so a context compact does not lose it. Explicit: *"cria as tasks no seu harness pra essa lista de tarefas pra caso o contexto seja compactado você não se perca no meio da implementação."* - **The kaggle CLI is available.** From message 0: *"a cli do kaggle está disponivel."* Use it for competition-side operations (submission upload, leaderboard queries, replay-zip downloads). ## Section 3 — Data selection hypotheses and evolution - **Original position:** the trainer had no data-selection knobs beyond `--max-rows`. Corpus was assumed uniform. - **Alefita's data-pollution thesis (2026-08-05):** *"a minha tese seria que os dados estão poluídos, nem todo dado do dataset é bom."* Proposed to prune weak agents' games from the training set. - **Implementation choice:** `--top-elo N` filter querying `agent_elo_daily WHERE source='remote'`, requiring BOTH sides in the top-N. Why both sides: a top-Elo agent's decisions vs an unknown opponent are still contaminated by the unknown side's weak counterfactuals. See [[pokemon_tcg_top_elo_curriculum_filter]]. - **Cost recognized before running the ablation:** the filter concentrates on strong games at the cost of deck-archetype coverage. Prediction: `--top-elo 50` on 1 day would zero out on `lb526_iono` (a low-Elo starter deck), because no top-50 agents play it. Prediction confirmed empirically at `1d_10ep_ON` (0% vs lb526). See [[pokemon_tcg_bc_curriculum_ablation]]. - **Empirical result:** the filter never wins in matched (days, epochs) pairs on vs-publics. Overfits on the smaller filtered set at `3d_10ep_ON` (16.9% overall, worst run). See [[pokemon_tcg_top_elo_curriculum_filter]] findings. - **Reframe for next experiment (2026-08-07):** *"a seleção deve e pode ser mais inteligente, está quase emergindo da estrutura que criamos no sqlite."* The `deck_elo_daily` + `deck_cards` tables already support stratification by archetype (guaranteed exposure to each top-N deck, per-matchup quotas, temporal decay). This is the next natural experiment, not a change to the current pipeline. Memory: `project-pokemon-tcg-sqlite-selecao-estratificada`. See also [[pokemon_tcg_sqlite_schema_current]]. - **`--max-rows-per-day 30000` cap:** chosen for **ablation parity** across day-count scales, not because 30k rows/day is the right training-time volume. Larger runs will drop this. Explicit thesis in [[pokemon_tcg_bc_curriculum_ablation]]. ## Section 4 — KV cache design evolution Three generations, each responding to a specific observation: 1. **No cache at all (up to 2026-08-05):** trainer re-decoded parquet row groups on every touch. Under TBPTT with a sizable lane pool this was measurably slow. 2. **Flat KV cache, FIFO eviction (2026-08-06 morning, commit `e772fe0`):** first attempt. Observation from Alefita: *"no começo fica bem parecendo que não funcionou, com muitos hits, dai depois, ele se aloca, corretamente, achei perfeito!"* Warmup was reading the corpus once; steady-state hit rate was excellent. But: under memory pressure, FIFO evicted row groups that would be needed again in the next epoch's replay of the same lane. 3. **Hierarchical hot/transient/SSD (2026-08-06 evening, commit `fa38caa`):** Alefita proposed *"quando o cache lotar e não for mais capaz de crescer, dai ele precisa sobrescrever o kv cache baseado em ordenação temporal das entries do cache a partir da métrica de hits."* We designed hot (pinned) + transient (LRU) with LFU-style promotion (`_HOT_PROMOTION_HITS=2`), and added an SSD spill tier so evicted transient entries survive to a later batch without re-decoding parquet. Also her explicit requirement: *"tanto o A quanto o B agora"* — Option A (opt-step eviction protection via `in_opt_step()`) plus Option B (hierarchical tiers). Both landed in the same commit. 4. **Val streaming (2026-08-06 evening, same commit):** driven by Alefita's frustration that val was silently materializing to RAM (~22 GiB) and OOM'ing at scale: *"eu tinha pedido já pra porra do validation também estar no kv fucking cache porra!"* Val now streams through its own `_ParquetRowGroupCache` with a separate SSD spill dir (`.cache_spill/val/`). Full mechanics in [[pokemon_tcg_kv_cache_hierarchical]]. Anchor commits `e772fe0`, `fa38caa`, `e8d6a4a`. ## Section 5 — BC curriculum ablation design - **Motivation:** validate the `--top-elo` curriculum thesis (Section 3) empirically across enough combinations to isolate the effect of filter versus data volume versus training length. - **Matrix:** `(1d, 3d, 5d) × (1ep, 10ep) × top-Elo OFF/ON`. Ten configs — the fourth `1d × 1ep × OFF/ON` pair was dropped because 1 epoch on 1 day is too small to say anything. - **Fixed knobs:** batch 1024, TBPTT chunk 16, val batch 1024, lr 2.46e-4, warmup 20 steps, aux_return 1.0, `--max-rows-per-day 30000`. Rationale for each in [[pokemon_tcg_train_config_reference]] "Current recommended baseline" section. - **Per-run tournament (option C):** 2 baselines + 4 starters + 3 strong public agents, sweep ON with 3 remote-top decks, 20 games per opponent per deck. Chosen over "just baselines" (too weak a signal per run) and "everything under public_agents" (too expensive at 10 runs). The C option explicitly picked because *"amanhã pela manhã vai ter finalizado tudo"* was the operational deadline she set for herself. - **Round-robin final:** all C(10,2)=45 pairs, no sweep, no baselines, 30 games per pair. Same deck for all so the comparison is apples-to-apples. Frames as *"proto self-play"* — same substrate an RL loop would use to sample opponents. - **Tournament JSON reports:** explicitly her callout — *"invés de um grep, usa um csv, ou um jsonl, qualquer coisa, pode ser transitório apenas, mas usar grep é loucura ainda mais que temos todo o controle do pipeline."* Replaced stdout scraping with structured JSON. See [[pokemon_tcg_tournament_system]]. - **`--sweep-source remote` (not local) default:** her insight — remote is populated by default from Kaggle replays; local requires local tournaments and is thinly populated. Committed with `--sweep-source` flag in `bb72620`. Findings and interpretation in [[pokemon_tcg_bc_curriculum_ablation]]. ## Section 6 — Findings that shifted our thinking - **`1d_10ep_ON` scored 0% vs `lb526`.** Alefita immediately recognized this as the coverage-cost signature: *"o modelo nunca foi exposto a esse tipo de deck... 0% contra lb526 1d on, pois ele nunca viu."* Direct confirmation of the pre-registered hypothesis. Not a "sinal preocupante" — an experimental signal. - **`5d_10ep_ON` closed the lb526 gap to 10%.** Only ON run that got out of zero. Interpretation: at 5 filtered days, the top-50 set contains enough deck diversity for lb526's archetype to sneak back in as a side effect. Coverage cost of the filter shrinks with dataset volume. - **`3d_10ep_ON` was the worst overall (16.9%).** Compare `3d_1ep_ON` = 20.4%: 10 epochs on the small filtered set regressed 3.5 points. Overfit signature. Same days, same filter, more training = worse. - **Anti-correlation between vs-publics and vs-peers.** `5d_10ep_OFF` is #1 on vs-publics (21.0%) and #8 on vs-peers (47.8%); `3d_1ep_ON` is tied #1 on vs-peers (53.2%) but only 20.4% on vs-publics. Interpretation: models that specialize on public agents become predictable to peers trained on similar data. Consequence: **vs-publics is the ladder-Elo proxy**, not vs-peers. Submission candidate accordingly is `5d_10ep_OFF`. - **Peer round-robin sits at 44–53% across all 10 models.** This is a useful architecture sanity signal within the August 6-7 suite: 10 models drawn from similar distributions and hyperparameter fan-out land in a normal Elo dispersion, with no collapse observed in that cohort. It does not certify the later shared-objective or validation contract; Stage 3/4 exposed a separate training failure. See [[pokemon_tcg_bc_curriculum_ablation]] finding 5 and [[pokemon_tcg_stage3_training_failure_postmortem]]. ## Section 7 — Incidents and operational lessons - **`setsid` unavailable on macOS (2026-08-07 dawn):** first suite launch attempted `setsid nohup` to detach from the harness process group so `/compact` couldn't SIGHUP the training. Failed silently on macOS which has no `setsid`. Fix: subshell + nohup (`(nohup bash ... &)`), reparents to init pid 1. Alefita then said *"roda normal que é melhor please"* and preferred the harness-attached background job with proper task notification — accepting the risk that a `/compact` could kill it, in exchange for automatic completion signaling. - **`/compact` teardown killed a training run (2026-08-07 first suite attempt):** the first background suite `betmh9lcc` died mid-epoch-5 of run 2 (`1d_10ep_ON`) with no stack trace when the harness compacted. Diagnosed via task summary "may have been running when the previous Claude Code process exited." Fix landed in the resume-aware suite driver: `--resume $LATEST_PKL --optimizer-state resume --scheduler-state resume` and skip-if-tournament-JSON-present at every level. See [[pokemon_tcg_tournament_system]]. - **KV cache SSD spill filled the disk (2026-08-07):** `.cache_spill/` under each `model/checkpoint/suite_*/` grew unbounded across runs (25 GiB alone for `suite_5d_1ep_ON`, ~70 GiB across nine completed runs). Training crashed with `OSError 28` mid-epoch-1 of the 10th run when tensorboard event writes failed. Fix: `rm -rf "$OUT_DIR/.cache_spill"` right after training completes in the driver script (commit `e8d6a4a`). Long-term the trainer's cache destructor should own it; out of scope for the fix. See [[pokemon_tcg_kv_cache_hierarchical]]. - **BSD seq quirk in the round-robin (2026-08-07):** `$(seq A B)` on macOS BSD `seq` with `A > B` emits a descending sequence (`10\n9`) instead of empty, causing one phantom self-pair matchup at the tail of the round-robin. Fix: replaced with C-style bash arithmetic for-loop `for ((i=0; i