Failure Modes

Failure Modes for Question Answering

Every deck has a FailurePolicy that decides what happens when you answer the gate question wrong. The policy's mode (a FailureMode) picks the strategy; FailurePolicyEngine.evaluate() turns a wrong answer + attempt count into a GateResult that the gate UI renders.

The four modes

RETRY

Answer wrong, try again — indefinitely. No attempt cap, no penalty, no lockout.

• Result: FailRetry(attemptsUsed, Int.MAX_VALUE) every time.
• UI: gate_state_wrong — shows the wrong-answer state and lets you retry immediately.
• Use case: lowest-friction mode; good for casual review decks. This is the Easy onboarding preset.

MAX_ATTEMPTS

Gives you a limited number of tries, then lets you through anyway (with a shame message) rather than locking you out.

• While attemptsUsed < maxAttempts: FailRetry(attemptsUsed, maxAttempts) — same wrong-answer/retry UI, now showing an attempts-remaining counter.
• Once attempts are exhausted: FailBypass(bypassMessage) — the gate lets you through, displaying bypassMessage (default: "Better luck next time 👀") via gate_state_bypass.
• Use case: keeps the gate from becoming a hard blocker if you genuinely don't know an answer. This is the Normal onboarding preset (maxAttempts = 3, penaltySeconds = 15 — note penaltySeconds is unused in this mode).

TIME_PENALTY

Every wrong answer costs you a fixed cooldown, no matter how many attempts you've made.

• Result: FailPenalty(penaltySeconds) on every failure — there's no attempt counting.
• UI: gate_state_penalty — presumably shows a countdown of penaltySeconds before you can try again.
• Use case: discourages guessing/spamming without ever letting you bypass entirely. This is the Hard onboarding preset (penaltySeconds = 60, hints disabled).

HARD_LOCK

The strictest mode: limited attempts, then a real lockout — no bypass.

• While attemptsUsed < maxAttempts: FailRetry(attemptsUsed, maxAttempts).
• Once attempts are exhausted: FailLockout(lockedUntilEpoch), where lockedUntilEpoch = now + lockoutMinutes * 60_000. Rendered via gate_state_lockout.
• There is no bypass path — you're locked out of the home screen until the lockout timer expires.
• Use case: the "no escape" option for decks you actually want to force mastery of.

Policy fields reference

Field	Used by	Meaning
mode	all	Which of the four modes above applies.
maxAttempts	MAX_ATTEMPTS, HARD_LOCK	Number of wrong answers allowed before bypass/lockout triggers. Ignored by RETRY and TIME_PENALTY.
penaltySeconds	TIME_PENALTY	Cooldown length (seconds) after each wrong answer.
lockoutMinutes	HARD_LOCK	Lockout length (minutes) once maxAttempts is exhausted.
bypassMessage	MAX_ATTEMPTS	Message shown when the user is let through after exhausting attempts.
hintAllowed	all (via GateController.hintAllowed())	Whether the gate screen offers a hint for the current question.

Built-in presets (FailurePolicyPresets, shown during onboarding)

Preset	mode	maxAttempts	penaltySeconds	hintAllowed
Easy	RETRY	—	30 (default, unused)	true
Normal	MAX_ATTEMPTS	3	15 (unused)	true (default)
Hard	TIME_PENALTY	— (default)	60	false
Custom	FailurePolicy() defaults	—	—	— (starting point for user-defined policies)

What happens on a correct answer (all modes)

Independent of mode, a correct answer always resolves to GateResult.Pass and advances the question's mastery streak (consecutiveCorrect): 2+ in a row → "learning" (level 1), 5+ in a row → "mastered" (level 2). Any wrong answer resets consecutiveCorrect to 0 and caps mastery at "learning" (level 1) if it was higher.

Attempt/session lifecycle

Attempt counting (attemptsUsed) is per gate session — it resets to 0 each time GateController.loadQuestion() picks a new question, not per-app-launch. A NoQuestion result (no active deck, or the deck is empty) is a separate case handled upstream in shouldShowGate(), not part of the failure-mode logic.