#+TITLE: Proposal — flashcard-stats.py refutation / claim-prompt mode

From: home session, 2026-06-21. Backlog, not urgent. Relates to the
refutation-drill deck being built in the home project.

* Problem

A new card family doesn't fit the linter: the *refutation / claim-prompt*
card. Its heading is a bare false claim ("The earth is flat.") and its
body is the rebuttal. This is a legit org-drill simple card (org-drill is
happy), but flashcard-stats.py — built for Q&A decks — trips two BLOCKING
checks on every such card, both false positives:

- *non-prompt heading*: a declarative claim has no '?' and no
  imperative verb, so it reads as "topic-as-heading not yet rewritten".
  But for this family the declarative claim IS the intended prompt.
- *answer leakage*: the claim's words necessarily reappear in the
  refutation, so front/back overlap is high. But the answer (the rebuttal)
  is not given away by the claim — there's no actual leakage.

Concrete: the home refutation-drill.org (6 cards) reports 6 non-prompt
headings + 1 leakage WARN, so flashcard-sync's gate blocks it entirely.
The deck currently has to be generated with the flashcard-to-anki.py
override, losing the safety net.

* Proposed fix

A per-deck opt-in marker that switches the two checks off for that file
only. Two options (your call):

1. A file-level keyword: =#+DECK_KIND: refutation= near the top. When
   present, flashcard-stats skips the non-prompt-heading check and the
   answer-leakage check for the whole file (keeps the others:
   missing-:ID:, *** Answer sub-headers, duplicate fronts, the
   non-blocking NOTEs).
2. A per-card tag: cards tagged =:claim:= (alongside =:drill:=) are
   exempted from those two checks individually.

Option 1 is simpler and matches how this deck works (the whole file is
one family). Option 2 is finer-grained if a deck ever mixes families.

Either way: document the new card family in flashcard-review.org (a
"Refutation / claim-prompt cards" subsection under Canonical Card Shape —
heading is the bare claim, body is snap-response + backups + named-fallacy
+ restate, Source footer), and note that flashcard-sync then works
normally on these decks.

* Affected files
- =flashcard-stats.py= — the check skip + (option 1) keyword parse / (option 2) tag check.
- =flashcard-review.org= — document the family + the marker.
- =flashcard-to-anki.py= / =flashcard-sync= — no change needed (they don't gate on heading form).
- Tests: add cases for a refutation-marked file passing despite declarative headings + claim/answer overlap.

* Companion context
The home deck's card format and the org-drill-fine / Anki-linter-fights
finding are written up in home:refutation-drill-sources.org (Tooling
note). The override command is documented there too.