mtg_python_deckbuilder/CONTRIBUTING_EDITORIAL.md

Editorial Contribution Guide (Themes & Descriptions)

Files

• config/themes/catalog/*.yml – Per-theme curated metadata (description overrides, popularity_bucket overrides, examples).
• config/themes/description_mapping.yml – Ordered auto-description rules (first match wins). {SYNERGIES} optional placeholder.
• config/themes/synergy_pairs.yml – Fallback curated synergy lists for themes lacking curated_synergies in their YAML.
• config/themes/theme_clusters.yml – Higher-level grouping metadata for filtering and analytics.

Description Mapping Rules

• Keep triggers lowercase; use distinctive substrings to avoid accidental matches.
• Put more specific patterns earlier (e.g., artifact tokens before artifact).
• Use {SYNERGIES} if the description benefits from reinforcing examples; leave out for self-contained archetypes (e.g., Storm).
• Tone: concise, active voice, present tense, single sentence preferred unless clarity needs a second clause.
• Avoid trailing spaces or double periods.

Adding a New Theme

1. Create a YAML file in config/themes/catalog/ (copy a similar one as template).
2. Add curated_synergies sparingly (3–5 strong signals). Enforced synergies handled by whitelist if needed.
3. Run: python code/scripts/build_theme_catalog.py --backfill-yaml --force-backfill-yaml.
4. Run validator: python code/scripts/validate_description_mapping.py.
5. Run tests relevant to catalog: pytest -q code/tests/test_theme_catalog_generation.py.

Reducing Generic Fallbacks

• Use fallback summary: set EDITORIAL_INCLUDE_FALLBACK_SUMMARY=1 when building catalog. Inspect generic_total and top ranked themes.
• Prioritize high-frequency themes first (largest leverage). Add mapping entries or curated descriptions.
• After lowering count, tighten regression thresholds in test_theme_description_fallback_regression.py (lower allowed generic_total / generic_pct).

Synergy Pairs

• Only include if a theme’s YAML doesn’t already define curated synergies.
• Keep each list ≤8 (soft) / 12 (hard validator warning).
• Avoid circular weaker links—symmetry is optional and not required.

Clusters

• Use for UI filtering and analytics; not used in inference.
• Keep cluster theme names aligned with catalog display_name strings; validator will warn if absent.

Metadata Info & Audit

• Backfill process stamps each YAML with a metadata_info block (formerly documented as provenance) containing timestamp + script version and related generation context. Do not hand‑edit this block; it is regenerated.
• Legacy key provenance is still accepted temporarily for backward compatibility. If both keys are present a one-time warning is emitted. The alias is scheduled for removal in version 2.4.0 (set SUPPRESS_PROVENANCE_DEPRECATION=1 to silence the warning in transitional automation).

Editorial Quality Status (draft | reviewed | final)

Each theme can declare an editorial_quality flag indicating its curation maturity. Promotion criteria:

Status	Minimum Example Commanders	Description Quality	Popularity Bucket	Other Requirements
draft	0+ (may be empty)	Auto-generated allowed	auto/empty ok	None
reviewed	>=5	Non-generic (NOT starting with "Builds around") OR curated override	present (auto ok)	No lint structural errors
final	>=6 (at least 1 curated, non-synergy annotated)	Curated override present, 8–60 words, no generic stem	present	metadata_info block present; no lint warnings in description/examples

Promotion workflow:

1. Move draft → reviewed once you add enough example_commanders (≥5) and either supply a curated description or mapping generates a non-generic one.
2. Move reviewed → final only after adding at least one manually curated example commander (unannotated) and replacing the auto/mapped description with a handcrafted one meeting style/tone.
3. If a final theme regresses (loses examples or gets generic description) lint will flag inconsistency—fix or downgrade status.

Lint Alignment (planned):

• draft with ≥5 examples & non-generic description will emit an advisory to upgrade to reviewed.
• reviewed with generic description will emit a warning.
• final failing any table requirement will be treated as an error in strict mode.

Tips:

• Keep curated descriptions single-paragraph; avoid long enumerations—lean on synergies list for breadth.
• If you annotate synergy promotions (" - Synergy (Foo)"), still ensure at least one base (unannotated) commander remains in examples for final status.

Automation Roadmap:

• CI will later enforce no final themes use generic stems and all have metadata_info.
• Ratchet script proposals may suggest lowering generic fallback ceilings; prioritize upgrading high-frequency draft themes first.

Common Pitfalls

• Duplicate triggers: validator warns; remove the later duplicate or merge logic.
• Overly broad trigger (e.g., art catching many unrelated words) – prefer full tokens like artifact.
• Forgetting to update tests after tightening fallback thresholds – adjust numbers in regression test.

Style Reference Snippets

• Archetype pattern: Stacks auras, equipment, and protection on a single threat ...
• Resource pattern: Produces Treasure tokens as flexible ramp & combo fuel ...
• Counter pattern: Multiplies diverse counters (e.g., +1/+1, loyalty, poison) ...

Review Checklist

• New theme YAML added
• Description present or mapping covers it specifically
• Curated synergies limited & high-signal
• Validator passes (no errors; warnings reviewed)
• Fallback summary generic counts unchanged or improved
• Regression thresholds updated if improved enough
• Appropriate editorial_quality set (upgrade if criteria met)
• Final themes meet stricter table requirements

Happy editing—keep descriptions sharp and high-value.

Minimum Example Commanders Enforcement (Phase D Close-Out)

As of Phase D close-out, every non-alias theme must have at least 5 example_commanders.

Policy:

• Threshold: 5 (override locally with EDITORIAL_MIN_EXAMPLES, but CI pins to 5).
• Enforcement: CI exports EDITORIAL_MIN_EXAMPLES_ENFORCE=1 and runs the lint script with --enforce-min-examples.
• Failure Mode: Lint exits non-zero listing each theme below threshold.
• Remediation: Curate additional examples or run the suggestion script (generate_theme_editorial_suggestions.py) with a deterministic seed (EDITORIAL_SEED) then manually refine.

Local soft check (warnings only):

python code/scripts/lint_theme_editorial.py --min-examples 5

Local enforced check (mirrors CI):

EDITORIAL_MIN_EXAMPLES_ENFORCE=1 python code/scripts/lint_theme_editorial.py --enforce-min-examples --min-examples 5

Alias YAML Lifecycle

Deprecated alias theme YAMLs receive a single release grace period before deletion.

Phases:

1. Introduced: Placeholder file includes a notes line marking deprecation and points to canonical theme.
2. Grace Period (one release): Normalization keeps resolving legacy slug; strict alias validator may be soft.
3. Removal: Alias YAML deleted; strict alias validation becomes hard fail if stale references remain.

When removing an alias:

• Delete alias YAML from config/themes/catalog/.
• Search & update tests referencing old slug.
• Rebuild catalog: python code/scripts/build_theme_catalog.py (with seed if needed).
• Run governance workflow locally (lint + tests).

If extended grace needed (downstream impacts), document justification in PR.