oracle-parser

name: oracle-parser description: "Use when doing any parser work — adding new Oracle text patterns, verb forms, phrase helpers, target patterns, subject handling, effect chain composition, fixing Unimplemented fallbacks, or understanding the parser architecture. This is the SINGLE SOURCE OF TRUTH for all oracle parser knowledge. Covers the nom combinator mandate, parsing priority system, AST type system, all helper modules, and contribution checklists."

Oracle Parser — Single Source of Truth

The Oracle parser converts MTGJSON Oracle text into typed AbilityDefinition structs that the engine executes. This skill is the authoritative reference for all parser work.

CR Verification Rule: Every CR number you write MUST be verified by grepping docs/MagicCompRules.txt BEFORE adding it to code. See Section 8.

1. Non-Negotiable Rules

These rules are defined in CLAUDE.md and are enforced without exception. Violations will be caught in review and must be fixed before merge.

⚠ RULE ZERO: Nom Combinators Are Mandatory — No Exceptions

All new parser code MUST use nom combinators from the very first line written. This is the single most important rule in the parser codebase. It has been violated repeatedly and is now enforced as a hard gate.

NEVER write any of these for parsing dispatch:

• find(), split_once(), contains(), starts_with() — for dispatch routing
• if lower.starts_with("destroy ") — use tag("destroy ").parse(lower) instead
• if lower.contains("target") — use scan_at_word_boundaries or a nom combinator instead
• text.find(' ').map(|i| &text[..i]) — use nom take_till or take_while

ALWAYS write:

• tag("destroy ").parse(lower)? — for known prefix dispatch
• alt((tag("destroy "), tag("exile "))).parse(lower)? — for multi-option dispatch
• nom_on_lower(text, lower, parser_fn) — for mixed-case text bridging to nom
• nom_on_lower_required(text, lower, parser_fn)? — same with ? propagation
• nom_parse_lower(lower, parser_fn) — when remainder is unused
• scan_at_word_boundaries(text, combinator) — for multi-position phrase matching

Nom combinator reference: See nom_combinators.md in this skill directory for the complete list of nom parsers and combinators organized by module. Consult this when choosing which combinator to use.

Copy-paste patterns + the enforcement gate: When you need to translate a string-method idiom into combinators, open crates/engine/src/parser/oracle_nom/PATTERNS.md — it indexes every common shape (strip prefix, strip suffix, optional trailing clause, alternatives, word-boundary scan, delimiter split, contains-check, peek-without-consume) with copy-pasteable code. The pre-commit hook scripts/check-parser-combinators.sh actively rejects new lines containing .strip_prefix(...), .strip_suffix(...), .contains("..."), .starts_with("..."), .ends_with("..."), .split_once(...), .find("..."), or .trim_end_matches("...") against string literals inside crates/engine/src/parser/. If a use is genuinely structural (post-tokenization punctuation cleanup, TextPair dual-string stripping, runtime char scans) annotate the line // allow-noncombinator: <one-line reason> per PATTERNS.md §9. Existing offenders are grandfathered; new code is gated.

The only acceptable uses of starts_with/strip_prefix in parser code:

• TextPair::strip_prefix for dual-string case-bridging operations (this is structural, not dispatch)
• Runtime array loops or char-level scanners
• Dynamic (non-literal) prefixes that can't be known at compile time

If you catch yourself writing string matching for parsing, STOP and rewrite with combinators before proceeding. There is no "convert later" — write it correctly the first time. This rule exists because every past violation required a review round-trip to fix.

Example — the wrong way vs. the right way:

// ❌ WRONG — string matching for dispatch
fn try_parse_destroy(lower: &str) -> Option<Effect> {
    if lower.starts_with("destroy ") {
        let rest = &lower["destroy ".len()..];
        // ... parse target from rest
    }
    None
}

// ✅ RIGHT — nom combinator from the first line
fn try_parse_destroy(lower: &str) -> Option<Effect> {
    let (rest, _) = tag("destroy ").parse(lower).ok()?;
    // ... parse target from rest using parse_target_phrase(rest)
}

See: oracle_casting.rs for verb dispatch via tag().parse(), oracle_trigger.rs for alt() dispatch.

Other Non-Negotiable Rules

Each rule below is defined in CLAUDE.md. One-sentence principle + codebase example.

Self-Review Checklist

Ask these four questions after every parser change:

1. Did I duplicate logic that an existing helper already handles?
2. Is this inline extraction something that should use a shared building block?
3. Would this logic work for 50 cards, or just the one I'm looking at?
4. Did I extend the general pattern, or write a special case?

If any answer is wrong, stop and refactor before moving on.

2. Architecture Overview

Parse Pipeline — Document-Level Two-Phase (parse → IR → lower)

parse_oracle_text() (oracle.rs, near the bottom of the file) is the public entry point and a thin wrapper over two phases: parse_oracle_ir() (IR production) followed by lower_oracle_ir() (IR lowering). Diagnostics flow through OracleDocIr.diagnostics → ParsedAbilities.parse_warnings.

Oracle text (from MTGJSON)
    ↓
parse_oracle_ir()               — oracle.rs: the priority router (see §3)
    ├─ normalize_card_name_refs()   — card name / "this creature" → ~ (once, at entry)
    ├─ pre-parsers (before the line loop): Saga chapters [oracle_saga.rs],
    │     Attraction visit lines [oracle_attraction.rs], Class levels
    │     [oracle_class.rs], Leveler LEVEL blocks [oracle_level.rs],
    │     Spacecraft "N+ |" thresholds [oracle_spacecraft.rs], Strive cost
    ├─ per line: strip_reminder_text(), then classify by priority slot (§3)
    ↓
OracleDocIr                     — oracle_ir/doc.rs: Vec<OracleItemIr> + diagnostics.
    │                             Core variants carry typed IR (EffectChainIr,
    │                             TriggerIr, StaticIr, ReplacementIr); PreLowered
    │                             variants carry already-assembled engine types.
    ↓
lower_oracle_ir()               — oracle.rs: exhaustive match on each OracleItemIr
    ↓                             (core IR → dedicated lowering fn; PreLowered → identity)
ParsedAbilities                 — abilities / triggers / statics / replacements /
                                  keywords / casting options + parse_warnings

Per-line classification inside parse_oracle_ir (simplified; §3 has the full slot table):

    ├─ Keywords-only            → keyword extraction
    ├─ "When/Whenever/At"       → parse_trigger_line()        [oracle_trigger.rs]
    ├─ Contains ":"             → activated ability parsing     [oracle_cost.rs + oracle_effect/]
    ├─ is_static_pattern()      → parse_static_line()          [oracle_classifier.rs → oracle_static/]
    ├─ is_replacement_pattern() → parse_replacement_line()     [oracle_classifier.rs → oracle_replacement.rs]
    ├─ Imperative verb          → parse_effect_chain()         [oracle_effect/]
    ├─ dispatch_line_nom()      → parse_effect_chain_with_context() [oracle_dispatch.rs → oracle_effect/]
    └─ Fallback                 → Effect::Unimplemented

IR Layer — oracle_ir/

Nom Combinator Layer — oracle_nom/

All parser branches delegate atomic parsing to shared nom 8.0 combinators:

Two-Phase Parse/Lower Architecture (clause level)

Within the effect branch, the parser uses the same two-phase approach at clause granularity: parse → AST → lower → Effect.

parse_effect_clause()                    — entry point (oracle_effect/mod.rs)
  → clause_shell::peel_clause()          — strip structural slots first (see below)
  → parse_clause_ast()                   — classify sentence shape → ClauseAst
  → lower_clause_ast()                   — convert AST to Effect
    → lower_subject_predicate_ast()      — for SubjectPredicate clauses
    → lower_imperative_clause()          — for Imperative clauses
      → parse_imperative_effect()        — try special cases, then delegate
        → parse_imperative_family_ast()  — classify verb family (imperative.rs)
        → lower_imperative_family_ast()  — convert to Effect

Clause Shell — Structural Slot Peeling (clause_shell.rs)

This is the destination architecture for structural slots. Phase 2 of the no-text-swallowing refactor (see data/parser-swallow-progress.md) inverts slot-consumption responsibility: instead of every body parser recognizing AND consuming surrounding structural slots inline (and silently dropping them when it forgets — the swallowing bug class), peel_clause(text) recursively strips slot-bearing prefixes/suffixes off the clause, accumulating them into a ClauseContext (synthesized attributes). The bare imperative remainder is handed to the existing body parsers, and the context is applied back onto the parsed result (apply_optional, duration(), condition()), so no recognized slot can be dropped.

Slots live in the shell today:

• Optional — "you may [verb]" → ClauseContext.optional (CR 608.2d), with a specialized-phrase blocklist (is_specialized_you_may_phrase) for "you may" constructions whose dedicated body parsers need the full surface form (alt-costs, impulse-draw permission, causative "have", retarget, Dig keep-from-among, specialized reveals).
• Duration — trailing duration suffix → ClauseContext.duration, delegating to strip_trailing_duration so the suffix table stays single-source (with an is_specialized_duration_carrier guard for parsers that need the suffix as a disambiguation signal, e.g. impulse-draw vs CastFromZone).
• Leading condition — "if [cond], [effect]" → ClauseContext.condition, delegating to strip_leading_general_conditional (which routes through parse_inner_condition).

Call site: parse_effect_clause() in oracle_effect/mod.rs (single peel point; oracle_trigger.rs and oracle_effect/subject.rs reference the peel in comments where their behavior depends on it). If the peeled variant lands in Unimplemented, the original text is retried — the shell is conservative.

Rule for new work: when adding handling for a new structural slot type (durations, optional clauses, conditions, and future siblings like APNAP order or activation limits), migrate it into the shell rather than adding another per-callsite strip_* pass: add a field on ClauseContext, a branch in peel_inner, an apply_* method, and remove the linear strip_* calls at the body-parser call sites. Do not add new inline slot consumption to body parsers.

Parser Dispatch Architecture

• Nom combinators handle ALL parsing dispatch — atomic, structural, sentence-level verb dispatch, and top-level routing.
• TextPair provides dual-string case-bridging (subject-predicate decomposition, clause AST classification). TextPair::strip_prefix is correct for these structural operations.
• oracle_classifier.rs owns reusable line-classification helpers such as trigger-prefix, static-pattern, and replacement-pattern detection. oracle.rs remains the priority router that calls them.
• oracle_special.rs owns the router-adjacent special helpers for solve conditions, Defiler two-line statics, die-roll tables, self-reference normalization for static parsing, and keyword-line parsers like Escape/Harmonize/Cumulative Upkeep.
• oracle_effect/conditions.rs owns leading-condition splitting and ability-condition helpers. oracle_effect/mod.rs remains the clause/effect orchestrator and re-exports split_leading_conditional.
• oracle_effect/search.rs owns search/seek filter parsing helpers. oracle_effect/mod.rs re-exports the stable search helper surface used by imperative and continuation parsing.
• New parser code MUST use nom combinators. starts_with/strip_prefix for parsing dispatch is NOT acceptable (see Rule Zero).

3. Parsing Priority System

Lines in parse_oracle_ir() (oracle.rs) are classified slot by slot. First match wins — the binding order is the SOURCE ORDER of the slots in the line loop, NOT the numeric labels. The labels are historical and non-monotonic (8b (early) runs before 0; loyalty 11 runs before the 3x keyword-line slots). When inserting a new slot, place it by evaluation position and grep // Priority in oracle.rs to see the live order; the table below mirrors that grep in evaluation order (one row per // Priority <label>: comment — the CI gate scripts/check-skill-doc.sh asserts the row count matches the code).

Before the line loop, parse_oracle_ir runs pre-parsers that consume whole line ranges: Saga chapters, Attraction visit lines, Class level sections (early return), Leveler LEVEL blocks, Spacecraft N+ | thresholds, and the Strive cost scan. Consumed line indices are skipped by the loop.

Unlabeled handlers interleaved between labeled slots are shown as — rows.

is_static_pattern() — oracle_classifier.rs

Gates Priority 7. Returns false for target-leading lines, then matches STATIC_CONTAINS_PATTERNS (word-boundary scan: "gets +", "have ", "can't attack", "nonland ", "you may spend mana as though", …), STATIC_PREFIX_PATTERNS, and is_static_compound_pattern() (graveyard/top-of-library/exile cast permissions, "spells can't be cast", flash grants, …). Check the constants in oracle_classifier.rs for the full lists.

is_replacement_pattern() — oracle_classifier.rs

Gates Priority 8. Matches REPLACEMENT_CONTAINS_PATTERNS ("would ", "prevent all", "enters tapped/untapped/prepared", "enter as a copy of", "become a copy of"), trailing " enter tapped/untapped", counter-prohibition phrases (CR 614.17), and is_replacement_compound_pattern() (as-enters-choose, enters/escapes + counter, tapped-for-mana + instead, madness discard).

4. Core Concepts

4a. Subject Stripping — The Key Design Decision

strip_subject_clause() removes subjects like "you", "target creature", "its controller" and recurses on the predicate. This simplifies parsing but discards semantic information.

Rule: If the subject encodes game-relevant information, intercept with a try_parse_* helper before stripping.

When to intercept: Subject determines WHO is affected, WHAT is referenced, or creates a sentence-internal dependency. When stripping is fine: "You draw three cards" (caster always draws), "Destroy target creature" (target is in verb phrase).

"Its controller gains life equal to its power"
    ❌ strip_subject_clause → loses "its controller" → GainLife { player: Controller }  BUG
    ✅ try_parse_targeted_controller_gain_life() → GainLife { player: TargetedController, amount: TargetPower }

The try_parse_* intercept pattern is used in:

• try_parse_subject_predicate_ast() in subject.rs — for subject-verb clauses
• lower_imperative_clause() in mod.rs — for imperative clauses with semantic subjects

4b. ClauseAst Type System

Top-level sentence classification — ClauseAst:

Predicate types — PredicateAst:

Imperative family dispatch — ImperativeFamilyAst (oracle_ir/ast.rs). The enum has three layers of variants: direct families, Structured(ImperativeAst) wrapping the structured families (Numeric, Targeted, SearchCreation, HandReveal, Choose, Utility), and a tail of keyword-action leaves (Explore, Connive, Investigate, Learn, Manifest, Proliferate, Populate, Goad, RollDie, VentureIntoDungeon, …):

Approximate dispatch order in parse_imperative_family_ast(): keyword-grant intercepts → CostResource → ZoneCounter → Numeric → Targeted → SearchCreation → Utility → Shuffle → HandReveal → Choose → keyword-action leaves → Put → YouMay. Read the function for the binding order before inserting a new family.

4c. Clause Splitting & Continuations

split_clause_sequence(text) splits multi-sentence text on . (Sentence), , then (Then), and certain , boundaries. Respects parentheses and possessive apostrophes.

Continuation absorption — a follow-up clause modifies a preceding effect:

Key functions: parse_followup_continuation_ast(), parse_intrinsic_continuation_ast(), continuation_absorbs_current(), apply_clause_continuation() — all in oracle_effect/sequence.rs.

4d. QuantityExpr / QuantityRef

pub enum QuantityExpr {
    Ref { qty: QuantityRef },   // dynamic — resolved from game state at runtime
    Fixed { value: i32 },       // literal constant
}

QuantityRef contains ONLY dynamic references (HandSize, LifeTotal, ObjectCount, TargetPower, Variable, etc.). Constants belong in QuantityExpr::Fixed — never put Fixed(i32) inside QuantityRef.

4e. Self-Reference Normalization

Before parsing, normalize_self_refs() replaces the card's name and phrases like "this creature" with ~. The canonical phrase list lives in oracle_util.rs as SELF_REF_TYPE_PHRASES — update the constant, not each consumer.

parse_target() handles both ~ and type phrases → TargetFilter::SelfRef automatically. Any parser function checking self-references gets this for free via parse_target.

5. Deep Dive — oracle_effect/ Directory

oracle_effect/
├── mod.rs                — Orchestrator: parse_effect_chain(), parse_effect_clause(), compound detection
├── conditions.rs         — Leading condition splitting, AbilityCondition extraction, condition bridges
├── imperative.rs         — Imperative verb family parsing: parse_*_ast() + lower_*_ast()
├── lower.rs              — Clause lowering helpers: strip_trailing_duration / strip_leading_duration
│                           (the live duration suffix/prefix tables), damage-player scopes
├── search.rs             — Search/seek parsing helpers: search filters, seek details, destinations
├── subject.rs            — Subject-predicate parsing: try_parse_subject_predicate_ast()
├── sequence.rs           — Clause boundary splitting and continuation absorption
├── token.rs              — Token creation: "create a 1/1 white Spirit token with flying"
├── animation.rs          — Animation/become: "becomes a 3/3 creature with flying"
├── become_copy_except.rs — Shared ", except <body>" clause for copy effects (CR 707.9 + CR 613.1a)
├── counter.rs            — Counter mechanics: put/remove/move/double counters
└── mana.rs               — Mana production and spend restrictions

AST type definitions (ClauseAst, ImperativeFamilyAst, ParsedEffectClause, etc.) live in oracle_ir/ast.rs — the former oracle_effect/types.rs was moved there as part of the IR layer.

Subject-Predicate Parsing — subject.rs

try_parse_subject_predicate_ast() parses sentences with explicit subjects.

Subject resolution via parse_subject_application():

Predicate hierarchy: try_parse_subject_continuous_clause() → try_parse_subject_become_clause() → try_parse_subject_restriction_clause() → fallback to strip_subject_clause() + imperative.

Imperative Family Verb Patterns

Numeric (parse_numeric_imperative_ast): draw N, gain N life, lose N life, gets +X/+Y, scry N, surveil N, mill N. Also used by try_parse_for_each_effect() via with_for_each_quantity().

ZoneCounter (parse_zone_counter_ast): destroy target/all, exile target/all, counter target spell, put N counters on target (delegates to counter.rs), remove N counters.

Targeted (parse_targeted_action_ast): tap/untap target, sacrifice, discard N, return to hand/battlefield, fight, gain control of.

CostResource (parse_cost_resource_ast): add {mana} (delegates to mana.rs), pay N life, pay {mana}, deal damage.

SearchCreation (parse_search_and_creation_ast): search your library, look at top N (dig), create token (delegates to token.rs), token copy.

Token (token.rs): Parses count → P/T → supertypes → colors → types → name → keywords → "where X is" expressions.

Animation (animation.rs): Parses "becomes a 3/3 [colors] [types] [keywords]" → AnimationSpec → Vec<ContinuousModification>.

Counter (counter.rs): try_parse_put_counter, try_parse_remove_counter, try_parse_move_counters, try_parse_multiply_counter, try_parse_double_effect.

Mana (mana.rs): try_parse_add_mana_effect (fixed symbols, colorless, any color, chosen color), parse_mana_spend_restriction, try_parse_activate_only_condition.

Compound Action Detection — mod.rs

• try_split_targeted_compound() — "verb target X and verb2 it": uses parse_target() remainder to find split, inherits parent target via replace_target_with_parent()
• try_parse_compound_shuffle() — "shuffle X and Y into libraries": two ChangeZone effects
• try_parse_for_each_effect() — "draw a card for each creature": delegates to parse_numeric_imperative_ast() + with_for_each_quantity() + thread_for_each_subject()
• parse_damage_player_scope() / parse_damage_each_player_scope() — shared damage-player routing helpers. Use these for exact each player / each opponent / each foe damage phrases before falling back to DamageAll. Keep this semantic split in oracle_effect/mod.rs; do not push it into parse_target(), which remains object/filter-oriented.

Special-Case Matchers in parse_effect_clause()

6. Other Parser Modules

The oracle_static/ Directory Split

The former single-file oracle_static.rs is now a directory. mod.rs owns the public parse_static_line() (two-phase: parse_static_line_ir → lower_static_ir), a shared prelude, and the re-export surface. Submodules:

Event-Context References

parse_event_context_ref() in oracle_target.rs handles trigger-event anaphoric references:

Must be checked BEFORE standard parse_target() for trigger-based effects.

The Possessive vs. Targeting Fork

Critical decision point — silent failure when wrong:

"Look at your hand"              → contains_possessive → target: Controller
"Look at target opponent's hand" → parse_target → target: Typed { controller: Opponent }

• Possessive forms that fall to parse_target → no target found → Unimplemented
• Targeting forms matched by contains_possessive → targeting phase skipped → wrong player affected

7. Building Block Reference

Search these modules BEFORE writing any new utility. Duplicating what already exists is a defect.

Where New Grammar Goes — Single-Authority Doctrine

Each grammar axis has exactly one home for NEW pattern recognition. Adding a pattern anywhere else creates a second authority that will drift:

• Durations — one grammar. Two duration tables exist today: oracle_nom/duration.rs::parse_duration (the nom combinator grammar) and oracle_effect/lower.rs::strip_trailing_duration (+ strip_leading_duration) — the suffix/prefix tables that the clause shell and the static/effect parsers actually run against, and the richer of the two ("for the rest of the game", "until ~ leaves the battlefield", mid-clause durations). Consolidation into oracle_nom/duration.rs is planned; until that port happens, new duration patterns go in strip_trailing_duration's table in oracle_effect/lower.rs (and strip_leading_duration for leading forms), so the clause shell picks them up for free. Do not add a third recognizer.
• QuantityRef recognition — new dynamic-quantity phrases go in oracle_nom/quantity.rs (parse_quantity_ref combinator and friends), never in oracle_quantity.rs, which is frozen legacy fall-through.
• Type phrases / targets — new type-phrase and target work composes the oracle_nom/target.rs combinators. oracle_target.rs remains the high-level extraction surface, but its building blocks are the nom combinators — extend those, not bespoke string logic.
• Conditions — parse_inner_condition in oracle_nom/condition.rs is the single condition recognizer (output type: StaticCondition). Its output is adapted into other condition layers by three bridges that MUST be kept exhaustive when StaticCondition gains variants: static_condition_to_trigger_condition (oracle_trigger.rs), static_condition_to_ability_condition (oracle_effect/conditions.rs), and static_condition_to_restriction_condition (oracle_condition.rs). A new StaticCondition variant that is silently unconvertible in a bridge is a swallow bug waiting to surface.
• Structural slots (optional, duration, leading condition, future siblings) — clause_shell.rs (see §2). New slot types migrate into the shell.

Damage-player routing (oracle_effect/mod.rs) — exact player-set phrases in damage effects have a dedicated helper path:

Rule: if the Oracle text is a damage effect that names a set of players, resolve that at the effect layer with these helpers. Do not teach parse_target() that each opponent is a player-damage target, because that would blur the object-target/filter boundary and reintroduce object-vs-player bugs.

Sub-Ability Chains & Target Propagation

parse_effect_chain() splits on . boundaries and links clauses as sub_ability. At runtime, resolve_ability_chain() walks the chain. When a parent ability has targets but the sub-ability does not, targets propagate automatically. Sub-abilities do NOT need their own target lists.

8. CR Annotation Protocol

MANDATORY for any code implementing MTG game rules. Non-optional.

Verification — Before Writing ANY CR Number

# REQUIRED — run these BEFORE writing the annotation:
grep -n "^701.21" docs/MagicCompRules.txt   # Verify keyword action number
grep -n "^702.122" docs/MagicCompRules.txt  # Verify keyword ability number
grep -n "^704.5a" docs/MagicCompRules.txt   # Verify SBA rule

If you cannot find the rule number, do NOT write the annotation. Flag it as "needs manual verification" instead. 701.x and 702.x numbers are arbitrary sequential assignments — LLMs consistently hallucinate them.

A wrong CR number is worse than no CR number. It creates false confidence that code was verified against the wrong rule.

Format

// CR 704.5a: A player with 0 or less life loses the game.
/// Checks state-based actions (CR 704).
// CR 702.2c + CR 702.19b: Deathtouch with trample assigns lethal (1).
// CR 704.3 / CR 800.4: SBAs may have ended the game during auto-advance.

• Prefix: Always CR. Never Rule, MTG Rule, or bare numbers.
• Description is mandatory — bare CR 704.5a with no explanation is not acceptable.
• + for interacting rules, / for alternative/overlapping rules.
• Only annotate game logic, not boilerplate/plumbing.

9. Checklists

9a. Adding a New Parser Pattern

Phase 1 — Identify Where It Belongs

• Imperative verb/family → the relevant parse_*_ast() in imperative.rs
• Subject + predicate → try_parse_subject_* in subject.rs
• Token creation → token.rs
• Animation/become → animation.rs
• Counter mechanics → counter.rs
• Mana production → mana.rs
• Continuation/absorption → sequence.rs
• Structural slot (optional / duration / leading condition) → clause_shell.rs (see §2)
• Duration phrase → strip_trailing_duration table in oracle_effect/lower.rs (see §7 doctrine)
• Dynamic quantity → oracle_nom/quantity.rs (never oracle_quantity.rs)
• Trigger → oracle_trigger.rs
• Static → oracle_static/ (dispatch in dispatch.rs, category submodules per §6)
• Replacement → oracle_replacement.rs
• Routing gate → is_static_pattern() / is_replacement_pattern() in oracle_classifier.rs (~line 398)

Phase 2 — Add the Pattern

• Write the parser test FIRST
• Use nom combinators from the first line (Rule Zero)
• Use existing helpers — parse_target(), parse_number(), contains_possessive(), parse_type_phrase()
• More specific patterns go BEFORE more general ones

Phase 3 — Handle the Subject

• Does the subject carry game-relevant info? → add try_parse_* interceptor
• Otherwise, subject stripping is fine

Phase 4 — Chain Composition

• Check continuation system in sequence.rs
• Check parse_effect_chain() for special chaining

Phase 5 — Routing

• Update is_static_pattern() or is_replacement_pattern() in oracle_classifier.rs if text is routed to the wrong parser

Phase 6 — Tests & Verification

• Parser unit tests for each new pattern
• Snapshot tests: oracle_ir/snapshot_tests.rs (IR + lowered parity, insta), plus per-module snapshot_tests.rs in oracle_static/
• cargo coverage — Unimplemented count should decrease
• Verify per CLAUDE.md § "Canonical verification pattern" — cargo fmt --all, then if tilt get uiresource clippy >/dev/null 2>&1: ./scripts/tilt-wait.sh --timeout 240 clippy test-engine card-data; else: cargo clippy --all-targets -- -D warnings + cargo test -p engine + ./scripts/gen-card-data.sh.

9b. Adding a New Effect Type

Cross-reference the /add-engine-effect skill for the full 8-phase lifecycle (types → handler → targeting → parser → interactive → multiplayer → frontend → AI → tests).

9c. Adding a New Trigger Event

Cross-reference the /add-trigger skill. Parser-specific: add pattern in try_parse_event(), wire subject into valid_card/valid_source, add tests.

Simple-verb events (e.g., stations, crews a vehicle, saddles a mount, becomes saddled): add a SimpleEvent::* variant in parse_simple_event, then a tag(...) arm in the appropriate alt() group. Compound events (e.g., saddles a mount or crews a vehicle) MUST precede their singular components so the compound matches first. Dispatch sets def.mode + valid_card (or valid_source for pronoun-context subjects).

Actor-side compound-subject matchers: when a trigger's subject filter may include non-source creatures (e.g., "Tiana or another legendary creature you control crews a Vehicle"), the runtime matcher MUST consult trigger.valid_card against the event's actor list (e.g., event.creatures) via matches_target_filter from game/filter.rs. See match_crews / match_saddles / match_saddles_or_crews + the shared match_actor_against_filter helper in trigger_matchers.rs for the canonical pattern.

Condition-scoped constraint recognition: trigger-frequency qualifiers like "for the first time each turn" must be detected against the post-split_trigger condition text only, NOT the full Oracle text — otherwise any card whose EFFECT text coincidentally contains the phrase is silently constrained. The phrase is then stripped from condition_text before dispatch so verbatim handlers (e.g., "whenever you cycle another card") hit unchanged, and the constraint is applied as a fallback in parse_trigger_line only when no stronger text-based constraint (OnlyDuringYourMainPhase, OncePerTurn via explicit text) was set. See the condition-scoped assignment block in parse_trigger_line for the canonical pattern.

9d. Adding a New Phrase Helper

1. Identify phrase variants
2. Implement via match_phrase_variants() in oracle_util.rs
3. Export from module
4. Add tests for all variants

9e. Adding a New Replacement Pattern

1. Add parse_* function matching the Oracle text
2. Insert at correct priority in parse_replacement_line() — before any overlapping pattern
3. Add parser tests

10. Common Pitfalls

11. Diagnostics — Swallow Detectors & parse_warnings

The parser must never silently discard Oracle text. Every clause must either be represented in the parsed AST OR cause the line to fail and yield Effect::Unimplemented carrying the original phrase. Anything in between is a parser lie.

The crates/engine/src/parser/swallow_check.rs module audits each card's parsed ParsedAbilities against its original Oracle text and emits a parse_warning for every marker phrase that has no AST representation. Findings surface in the coverage report via CardFace::parse_warnings (also written into each card's entry in client/public/card-data.json).

Reading current swallow gaps:

# Count total active warnings
jq -r '[.[] | .parse_warnings // [] | .[]] | length' client/public/card-data.json

# Top clustered warning patterns by likely shared fix.
cargo run -p engine --bin coverage-report -- data --brief \
  --write-warning-patterns /tmp/parser-warning-patterns.json >/tmp/coverage.json
jq -r '
  [.[] | select(.category=="swallowed-clause")]
  | sort_by(-.otherwise_supported_cards, -.card_count)
  | .[0:25][]
  | "\(.otherwise_supported_cards) otherwise / \(.card_count) cards / \(.single_gap_cards) single | \(.pattern) | \(.example_cards|join(", "))"
' /tmp/parser-warning-patterns.json

# Drill down into one exact warning pattern. This uses the same clustering
# function as parser-warning-patterns.json and includes support status,
# gap count, warning text, parsed labels, and gap details.
cargo run -p engine --bin coverage-report -- data \
  --warning-category swallowed-clause \
  --warning-pattern 'Replacement_Instead: instead' \
  --warning-limit 20 >/tmp/warning-drilldown.json

# Drill down into a broader detector family when exact-pattern slices are too narrow.
cargo run -p engine --bin coverage-report -- data \
  --warning-detector Replacement_Instead \
  --warning-limit 20 >/tmp/warning-drilldown.json

# Include the full parse_details tree and exported CardFace JSON when needed.
cargo run -p engine --bin coverage-report -- data \
  --warning-detector DynamicQty \
  --warning-full \
  --warning-limit 5 >/tmp/warning-drilldown-full.json

Detector class prefixes (one row per detector in swallow_check.rs):

Current card-data.json stores parse warnings as structured diagnostics, not legacy strings:

{ "type": "SwallowedClause", "detector": "Replacement_Instead", "description": "...", "line_index": 0 }

Use --warning-detector <detector> for broad-family triage and --warning-pattern '<detector>: <normalized excerpt>' for exact shared-fix slices. A high supported_cards count in the drilldown means the warning is likely detector noise or an already-parsed semantic that swallow_check.rs does not recognize yet; inspect parsed_labels before adding parser behavior.

Workflow:

1. Start with parser-warning-patterns.json sorted by otherwise_supported_cards; this finds the largest likely false-positive or minor-chomp groups.
2. Run coverage-report --warning-pattern ... or --warning-detector ... and inspect supported, gap_count, parsed_labels, and gap_details before editing parser code.
3. Classify the pattern: detector false positive, parsed primary effect with missing modifier, or real parser gap.
4. When fixing a real swallow, identify the dispatch site that recognized the marker but failed to either capture or chomp it. The fix is almost always at one of two places: the upstream recognition (route through the right try_parse_* interceptor) or the downstream chomping loop (add a missing arm). The peek-vs-chomp pitfall in §10 is the recurring root cause.
5. After fixing, regenerate (./scripts/gen-card-data.sh) and rerun the same drilldown; warnings should drop by exactly the affected class size unless other detectors were un-muted.
6. Suppression rule — swallow_check.rs may skip detectors when a card already has stronger parser failures; fixing one issue can un-mute additional detector warnings on the same cards.

Companion Python audit: scripts/swallow_audit.py runs the same heuristics over coverage-data.json independently of the Rust runtime. Use it for cross-checking, or for exploring novel detector classes before promoting them to swallow_check.rs.

12. Self-Maintenance

After completing work using this skill:

1. Verify references by running ./scripts/check-skill-doc.sh
2. Update the priority table (§3) if slots were added/removed/renamed in parse_oracle_ir — the gate compares the table against the // Priority <label>: comments
3. Update the AST family tables (§4b) if new families or continuations were added
4. Update the deep dive (§5) if new sub-modules were added to oracle_effect/
5. Update the module catalog (§6) if new oracle_*.rs modules or oracle_static/ submodules were added

Verification Gate — scripts/check-skill-doc.sh

The verification script lives at scripts/check-skill-doc.sh and runs in CI (rust-lint job, alongside the parser combinator gate), so this document cannot silently drift from the source tree. It asserts three invariant families:

1. Paths — every parser file/directory documented here exists.
2. Anchor symbols — the load-bearing functions named in this document (parse_oracle_ir, lower_oracle_ir, peel_clause, parse_inner_condition, the three condition bridges, strip_trailing_duration, …) still live in the documented files.
3. Priority table sync — the §3 table's labeled-row count equals the number of // Priority <label>: slot comments in oracle.rs, and every label that appears in code appears in the table. Cosmetic doc edits don't trip it; adding, removing, or renaming a slot without updating §3 does.

./scripts/check-skill-doc.sh   # exit 0 = doc in sync; non-zero lists drift

When the gate fails: update the relevant section here (not the script's expectations) unless the code change itself was wrong. When documenting a new slot, give it a | \label` |row in §3; unlabeled interleaved handlers use| — |` rows, which the gate ignores.