audit-deck

name	audit-deck
description	Hunt for one previously-undocumented defect, doc drift, missing test, or inconsistency; file it via Skill(create-card). AUTO-INVOKE on "find me a bug", "audit X", "check for inconsistencies", or /audit-deck. Inconsistencies are the primary lead.
argument-hint	optional area filter within the project (consuming repo defines its default scope in `.game-of-cards/hooks/audit-deck.md`)

When to invoke

Invoke when the user says "find me a bug", "audit X", "check for inconsistencies", "what could be wrong", "hunt for issues", "scan the codebase", "look for gaps", or invokes /audit-deck. Also covers architectural ugliness, code smells, and inconsistencies (XP spike + Scrum backlog refinement).

Preflight

If any ! block below shows goc: command not found, Permission for this action has been denied, or no such file or directory: .game-of-cards/deck/, stop and invoke Skill(kickoff) first. Kickoff detects which setup step is missing (CLI not installed, Bash allowance not granted, project state not scaffolded) and walks the user through it. Re-invoke this skill only after kickoff completes.

Context (read but distrust — these are hypotheses, not ground truth)

!goc

!goc --done

!goc --status disproved

!goc --tag unverified

!cat .game-of-cards/hooks/audit-deck.md 2>/dev/null || true

Audit

Find one previously-undocumented defect — bug, derivation gap, doc drift, missing test, wrong concept, architectural ugliness, code smell, or inconsistency — and file it via Skill(create-card). Treat nothing as truth; inconsistencies and contradictions are the primary lead, and "I looked and didn't find anything" is a failure mode, not an acceptable outcome.

User argument: $ARGUMENTS — if non-empty, narrow within the default scope (the consuming repo defines this in .game-of-cards/hooks/audit-deck.md). Out-of-scope arguments are flagged and ignored.

Long-form material lives in reference.md — a sibling file in this skill's directory. Read the named section only when the situation actually applies:

Situation	reference.md section
Why the audit exists; what counts as a defect	Rationale
No probe configured; need probe ideas	Typical probe recipes
A candidate touches a design decision / unclear gate	Consulting the project rubric
Filing a parser/emitter/serializer defect	Reachability paths
A round ends with unfollowed or zero candidates	Park-or-disprove: bounds and escape valve
Writing the commit	Canonical commit subject

Mindset (compressed)

• Code is suspect first; documentation second. When code and the project's stated principles disagree, the default presumption is the code drifted. Documentation is the target the code is meant to approximate; the consuming repo's hook (above) names the doc surfaces that count as ground truth.
• Empirical or it didn't happen. Every reported defect needs evidence — no "I think this might be." For behavioral defects (bugs, derivation gaps, missing tests), evidence is a reproduce.py that prints output proving the defect. For structural defects (architectural ugliness, code smells, doc drift, inconsistencies), evidence is the citation set: every duplicated site, every contradicting passage, every contract violation, quoted with file:line. Either form is concrete; "it feels off" is not.
• Disproved dedup before filing. Grep goc --status disproved for the candidate's identifying string. Re-promote only with new evidence (cited code changed since the rebuttal date).
• Hunt the big thing first. Contribution ladder: high outranks medium outranks low. Doc claims that contradict an authoritative source are contribution: high + tags: [documentation], NOT low.
• File every confirmed defect regardless of queue depth. Queue length is a transparency signal, not backpressure.
• Flag, don't fix. This skill ships a documented defect, not a patch.

When a candidate touches a substantive design decision or the right gate is unclear, consult the project rubric first — reference.md § Consulting the project rubric.

Phase 1 — Probe (run BEFORE static hunting)

Static analysis converges to "no new defect" within ~5 rounds. Behavioral defects — NaN/Inf, divergence, silent boundary-state corruption — require running the actual project. Run the probe AND doc-quality hunters concurrently; the probe is I/O-bound and the doc hunters have no probe dependency.

The consuming repo defines its probe recipe in .game-of-cards/hooks/audit-deck.md (already loaded above); generic probe shapes in reference.md § Typical probe recipes.

Triage:

• Probe surfaces NaN/Inf, out-of-range metric, state-leak diff, or a project-specific [FAIL] marker: that's the primary lead. Skip Phase 2, go to Phase 3 (file).
• Probe suggestively close to a documented bound: record as tags: [unverified] with a sweep recipe.
• Probe clean (or no probe configured): proceed to Phase 2 static hunting.

Phase 2 — Hunt (parallel agents in a single message)

The consuming repo defines its hunter roster in .game-of-cards/hooks/audit-deck.md (already loaded above) — which specialized agents to spawn for which scopes, and which surfaces each is briefed against.

If no hunter roster is configured, default to spawning ONE general-purpose agent with the user's scope and the briefing items below — every Claude Code installation has this agent available.

Brief each agent with:

1. The catalog floor — point at the goc CLI queries for open / done / disproved / unverified. Agents should goc show <title> for full READMEs of specific entries.
2. The user's scope.
3. Mindset: prioritize contribution: high (structural / algorithmic) over contribution: low (text-rot).
4. Deliverable: top 3 candidates with file:line citation, a contribution classification (high/medium/low) + relevant tags, and a falsifiable prediction about what deck/<title>/reproduce.py would print.

For model-tier guidance (e.g. mandating model: "opus"), see .game-of-cards/tooling-conventions.md.

If a hunter returns three contribution: low candidates and no high, send it back with explicit pointers to under-audited high-impact seams (the integrator, the core update logic, state- restore paths, default-parameter table, public API contracts).

Phase 3 — File (one card per confirmed defect)

For each confirmed candidate:

1. Read the cited code yourself. Agents hallucinate file:line.
2. Disproved-dedup grep. Before drafting reproduce.py, grep the candidate's identifying string against existing disproved bodies. If a rebuttal exists, re-read it.
3. Name the reachability path in ## Why it matters. For parser / emitter / serializer / storage-layer defects, name the path that produces the offending input — full convention in reference.md § Reachability paths.
4. Hand to Skill(create-card) for the actual filing (title, scaffold, body, DoD, reproduce.py).
5. Sibling sweep after confirmation. Grep for the same root-cause shape in adjacent modules. File every confirmed sibling as a separate card. If the sweep would produce a 4th instance of an already-catalogued family, file the architectural meta-fix instead.

Park-or-disprove unfollowed candidates (mandatory)

Each hunter typically returns 3 candidates; you can verify and file 1–2 in a single round. The remaining candidates MUST go somewhere durable before commit:

1. Filed as a new card via Skill(create-card).
2. Disproved via Skill(advance-card) <title> disproved — when you read the cited code and the claim is wrong on its face.
3. Unverified via Skill(create-card) ... --tag unverified — when the candidate has substance but no reproduce.py budget this round. Body must include: hypothesis with file:line (verbatim quote), why deferred, falsification recipe, agent that surfaced it.

This rule applies even when the round produces a confirmed defect; bounds, the hallucination escape valve, and the empty-round restart rule are in reference.md § Park-or-disprove.

Phase 4 — Commit

When all deck/<title>/ dirs (filed + disproved + unverified) are written, commit them according to the consuming repo's normal commit workflow and any GoC hook it defines. The deck-validate hook rejects schema violations. Subject shape: new card: <one-line description> — full rules in reference.md § Canonical commit subject.

Output

Brief summary in chat (≤200 words):

• The new card title(s) (<title> — <subject>).
• Where it was found (file:line).
• One verification number from deck/<title>/reproduce.py.
• The contradicted doc/comment (quoted, one line).
• Disproved candidates added this run, if any (one-liner each).
• Unverified candidates parked this run, if any.
• The commit hash, if this run created a commit.

Full writeup, code quotes, empirical output, and proposed fix all live in deck/<title>/README.md. Do not duplicate them in chat.

Cross-references

• Skill(create-card) — actual filing (title, scaffold, body, DoD).
• Skill(advance-card) — for disproved flips during verification.
• Skill(scan-deck) — dedup queries against existing queues (open / done / disproved / unverified).
• Skill(card-schema) — DoD format, decision-gate body contract, canonical tag predicates.
• Project commit workflow — final checks, staging, and commit.