step3/docs/QUESTION_BANK_GAMIFICATION.md

Question bank gamification

Objective

Make studying easy to begin, satisfying to continue, and valuable to repeat while optimizing for durable learning rather than compulsive use. The core engagement loop is:

Answer -> immediate insight -> visible progress -> useful reward -> clear next goal

Success means learners return consistently, improve weak areas, complete spaced reviews, and become more exam-ready. Raw time in the application is not itself a success metric.

Product principles

• Reward demonstrated learning, recovery from errors, and breadth of coverage.
• Make reward rules understandable and resistant to farming.
• Give every study session a user-selected finish line and satisfying conclusion.
• Keep stopping controls as prominent as continuation controls.
• Do not lock core questions, explanations, or remediation behind RZ Coin.
• Prefer weekly consistency over an indefinitely escalating daily streak.
• Keep social participation optional and private by default.
• Never use paid randomized rewards, near-miss effects, disguised odds, or loss-heavy messaging.

Mastery paths

Show mastery for each system, topic, and tested concept. Mastery should combine:

• First-attempt correctness
• Question difficulty
• Recency and spaced-review status
• Successful recovery after an incorrect answer
• Breadth across related concepts

Mastery must not be a reskinned count of questions answered. Each topic should show its current state, evidence behind that state, and the next useful action. Suggested states are Unseen, Learning, Practicing, Strong, and Mastered.

The dashboard should highlight progress in weak areas and recently mastered concepts. A system cannot reach its highest rank by repeatedly farming a narrow set of easy questions.

RZ Coin economy

Award RZ Coin for learning behaviors:

• A first correct attempt
• Correctly answering a genuinely difficult question
• Completing a scheduled review
• Converting a previously missed concept into a correct delayed review
• Improving a weak topic
• Completing a timed or simulated-exam block
• Meeting a balanced daily or weekly study goal

Do not primarily reward elapsed time, retries, repeated easy questions, or raw volume. Apply diminishing or zero rewards to repeated content where necessary. All awards should be server-authoritative, idempotent, and recorded in the coin ledger with a reason code.

Appropriate purchases include:

• Question-bank reset tokens
• Cosmetic themes, avatars, profile frames, titles, and study environments
• Optional analytics presentations
• Limited streak protection
• Collectible medical artifacts and achievement displays

Purchases must disclose their exact price and effect. Randomized paid purchases and purchasable power over exam scoring or question correctness are prohibited.

Daily and weekly missions

Offer three short daily missions that reflect the learner's needs, for example:

• Complete 10 scheduled reviews.
• Answer five difficulty-4 questions.
• Improve one weak system.
• Complete a timed block without skipping.

Allow a learner to replace a mission that does not fit the current study plan. Missions should not require excessive daily volume or encourage answering after fatigue has clearly degraded performance.

Weekly goals should emphasize consistency and breadth, such as studying on four days, reviewing three systems, or clearing a reasonable number of overdue reviews. A flexible weekly target is preferred to an endless daily streak.

Session goals and completion

At the beginning of a session, let the learner choose a finish line:

• A number of questions
• A study duration
• One weak topic
• One simulated-exam block
• All currently due reviews, subject to a reasonable cap

At the finish line, present a completion screen before offering more work. The primary actions should give equal visual weight to Finish for today and a clearly sized optional next block. Do not create artificial unfinished states to pressure continuation.

The end-of-session summary should include:

• Questions completed and first-attempt accuracy
• Concepts newly mastered
• Previously missed concepts recovered
• Weak areas improved
• RZ Coin earned, with award reasons
• Readiness change, with an explanation of how it was calculated
• A recommended next session

Progression and personal records

Introduce skill-based ranks such as Intern, Resident, Chief, and Attending. Rank advancement should require mastery across several systems, successful delayed reviews, and performance on appropriately difficult items. It must not depend only on account age or total answers.

Personal records should measure meaningful improvement:

• Best timed-block accuracy at a defined difficulty mix
• Longest first-attempt correct streak at difficulty 4 or higher
• Most concepts mastered in a week
• Largest reduction in overdue reviews
• Greatest improvement in a previously weak content area

Record definitions must remain stable and visible so the learner understands what was achieved.

Social features

Potential opt-in features include private study groups, cooperative weekly goals, friend challenges, and anonymous percentile bands. Prefer cooperative goals over leaderboards based on raw volume.

Do not expose failure, study time, predicted score, or inactivity publicly by default. Users must be able to leave a group, hide a statistic, and disable social notifications.

Notifications and streak safeguards

• Let users choose notification categories, quiet hours, and frequency.
• Use factual reminders rather than guilt, urgency, or threatened loss.
• Allow recovery days and planned breaks.
• Cap streak-protection use and describe it transparently.
• Never send repeated prompts after a learner chooses to finish a session.
• Detect unusually long sessions and offer a neutral break reminder.

Recommended delivery order

Phase 1: foundation

1. Define the mastery model and expose topic-level progress.
2. Add server-authoritative RZ Coin awards for approved learning events.
3. Add user-selected session goals and an end-of-session summary.
4. Add daily missions with one replacement per day.

Phase 2: progression

1. Add weekly consistency goals.
2. Add breadth-based ranks and personal records.
3. Expand the RZ Coin store with cosmetic and utility items.
4. Add limited streak protection and recovery days.

Phase 3: social and optimization

1. Add private cooperative groups and friend challenges.
2. Personalize missions using weak-area and spaced-review data.
3. Experiment with presentation and pacing under the guardrails below.

Measurement

Primary metrics should measure learning and healthy retention:

• Weekly active learners completing at least one meaningful study goal
• Scheduled-review completion rate
• Delayed retention after 7, 21, and 45 days
• Recovery rate for previously missed concepts
• Breadth of systems studied
• Timed-block and simulation improvement
• Percentage of sessions ending at the learner's selected finish line

Monitor guardrail metrics alongside product experiments:

• Extremely long sessions and late-night continuation
• Rapid repetitive answering consistent with coin farming
• Notification opt-out and mute rates
• Mission abandonment after oversized goals
• Increased accuracy volatility associated with fatigue
• Support reports involving pressure, anxiety, or confusing rewards

Do not optimize an experiment solely for session length, questions per session, notification opens, or coin spending. A change should improve at least one learning or healthy-retention metric without materially degrading the guardrails.

Initial acceptance criteria

The first release is complete when:

• Mastery is computed from correctness, difficulty, recency, and review outcomes.
• Coin awards are idempotent and cannot be earned repeatedly from the same event.
• Every award and purchase has a ledger entry and visible reason.
• A learner can set and complete a bounded session goal.
• The completion screen offers both stopping and continuing without deceptive emphasis.
• Daily missions target due reviews or genuine coverage gaps and can be replaced.
• Core educational content remains available without coin purchases.
• Product analytics include the primary and guardrail metrics above.