mtg_python_deckbuilder/docs/theme_taxonomy_rationale.md

Theme Taxonomy Rationale & Governance

This document captures decision criteria and rationale for expanding, merging, or refining the theme taxonomy.

Goals

• Maintain meaningful, player-recognizable buckets.
• Avoid overspecialization (micro-themes) that dilute search & filtering.
• Preserve sampling diversity and editorial sustainability.

Expansion Checklist

A proposed new theme SHOULD satisfy ALL of:

1. Distinct Strategic Identity: The game plan (win condition / resource axis) is not already adequately described by an existing theme or combination of two existing themes.
2. Representative Card Depth: At least 8 broadly played, format-relevant cards (EDHREC / common play knowledge) naturally cluster under this identity.
3. Commander Support: At least 3 reasonable commander candidates (not including fringe silver-bullets) benefit from or enable the theme.
4. Non-Subset Test: The candidate is not a strict subset of an existing theme's synergy list (check overlap ≥70% == probable subset).
5. Editorial Coverage Plan: Concrete initial examples & synergy tags identified; no reliance on placeholders at introduction.

If any criterion fails -> treat as a synergy tag inside an existing theme rather than a standalone theme.

Candidate Themes & Notes

Candidate	Rationale	Risks / Watchouts	Initial Verdict
Combo	High-synergy deterministic or infinite loops. Already partly surfaced via combo detection features.	Over-broad; could absorb unrelated value engines.	Defer; emphasize combo detection tooling instead.
Storm	Spell-chain count scaling (Grapeshot, Tendrils). Distinct engine requiring density/rituals.	Low breadth in casual metas; may overlap with Spellslinger.	Accept (pending 8-card list + commander examples).
Extra Turns	Time Walk recursion cluster.	Potential negative play perception; governance needed to avoid glorifying NPE lines.	Tentative accept (tag only until list curated).
Group Hug / Politics	Resource gifting & table manipulation.	Hard to score objectively; card set is broad.	Accept with curated examples to anchor definition.
Pillowfort	Defensive taxation / attack deterrence (Ghostly Prison line).	Overlap with Control / Enchantments.	Accept; ensure non-redundant with generic Enchantments.
Toolbox / Tutors	Broad search utility enabling silver-bullet packages.	Tutors already subject to bracket policy thresholds; broad risk.	Defer; retain as synergy tag only.
Treasure Matters	Explicit treasure scaling (Academy Manufactor, Prosper).	Rapidly evolving; needs periodic review.	Accept.
Monarch / Initiative	Alternate advantage engines via emblems/dungeons.	Initiative narrower post-rotation; watch meta shifts.	Accept (merge both into a single theme for now).

Merge / Normalization Guidelines

When overlap (Jaccard) between Theme A and Theme B > 0.55 across curated+enforced synergies OR example card intersection ≥60%, evaluate for merge. Preference order:

1. Retain broader, clearer name.
2. Preserve curated examples; move excess to synergy tags.
3. Add legacy name to aliases for backward compatibility.

Example Count Enforcement

Threshold flips to hard enforcement after global coverage >90%:

• Missing required examples -> linter error (lint_theme_editorial.py --require-examples).
• Build fails CI unless waived with explicit override label.

Splash Relax Policy Rationale

• Prevents 4–5 color commanders from feeling artificially constrained when one enabling piece lies just outside colors.
• Controlled by single-card allowance + -0.3 score penalty so off-color never outranks true color-aligned payoffs.

Popularity Buckets Non-Scoring Principle

Popularity reflects observational frequency and is intentionally orthogonal to sampling to avoid feedback loops. Any future proposal to weight by popularity must include a diversity impact analysis and opt-in feature flag.

Determinism & Reproducibility

All sampling randomness is derived from seed = hash(theme|commander); taxonomy updates must document any score function changes in CHANGELOG.md and provide transition notes if output ordering shifts beyond acceptable tolerance.

Governance Change Process

1. Open a PR modifying taxonomy YAML or this file.
2. Include: rationale, representative card list, commander list, overlap analysis with nearest themes.
3. Run catalog build + linter; attach metrics snapshot (preview_metrics_snapshot.py).
4. Reviewer checks duplication, size, overlap, enforcement thresholds.

Future Considerations

• Automated overlap dashboard (heatmap) for candidate merges.
• Nightly diff bot summarizing coverage & generic description regression.
• Multi-dimensional rarity quota experimentation (moved to Deferred section for now).

---

Last updated: 2025-09-20