tutor-service/docs/planning/GAMIFICATION.md

# Learning Gamification Design

## Source Reference

This note adapts ideas from the user-provided game-design summary:

Attached game-design markdown summary provided by the user.

The product should use game design to create healthy learning persistence, not
exploitative compulsion. The goal is a strong achievement loop that makes users
want to return because they feel measurable progress toward interview readiness.

## Design Translation

### Experience before content volume

The source material emphasizes that content is surface and experience is the
core. For this product, a large question bank is not enough. The core experience
must be:

- "I know what I am weak at."
- "The next question is exactly the right challenge."
- "I can feel myself becoming interview-ready."
- "Every session ends with a clear win and a next step."

### Flow and adaptive difficulty

Learning sessions should target a flow band:

- too easy: boredom and low trust
- too hard: shame, avoidance, and churn
- just above current ability: useful struggle and pride

The tutor should adjust difficulty using learner memory:

- lower difficulty after repeated failure
- increase specificity after vague but correct answers
- add time pressure only after concept mastery is stable
- switch from recall to applied scenario questions as mastery rises
- insert recovery questions after a hard miss

### Learning main loop

Use a repeated loop similar to challenge, action, reward:

```text
Readiness goal
  -> interview question
  -> user answer
  -> rubric feedback
  -> follow-up or correction
  -> memory update
  -> visible progress
  -> next best challenge
```

This loop should be short enough to complete in 5-10 minutes, with optional
longer sessions composed from multiple loops.

### Expectation curve

Each session needs a visible promise:

- today's target concept
- expected time
- reward or unlock
- interview readiness impact
- next milestone preview

The product should maintain open loops carefully:

- show what the next unlock or milestone is
- avoid creating many unfinished tasks at once
- close each session with a concrete result

### Growth lines

Use two growth lines:

1. Permanent mastery growth
   - concept mastery
   - misconception resolved
   - interview skill badges
   - portfolio of strong answers

2. Seasonal or campaign growth
   - weekly interview sprint
   - target-company prep campaign
   - stack-specific challenge ladder
   - mock interview streak

Permanent growth provides long-term identity. Campaign growth provides freshness
without erasing real learning progress.

## Product Systems

### Readiness Map

A role-specific map that shows concept readiness:

- unknown
- fragile
- improving
- interview-ready
- strong signal

### Challenge Ladder

Each concept gets a ladder:

1. define
2. explain tradeoffs
3. debug a scenario
4. design under constraints
5. answer under interview pressure

### Boss Questions

After a cluster of concepts is stable, the user gets a boss-style integrated
question. Example:

"Design a rate-limited API endpoint with database transactions, cache behavior,
failure handling, and test strategy."

### Reward Types

Prefer meaningful rewards:

- readiness percentage
- concept unlocks
- strong answer saved to portfolio
- mock interview token
- new scenario type unlocked
- visual certificate for a completed track
- generated review card or diagram

Avoid rewards that are disconnected from learning value.

### Session Ending

Every session should end with a strong closure:

- one thing improved
- one misconception discovered or resolved
- one recommended next step
- one visible progress change

## Safety Rules

- Do not use gambling-like random rewards as the primary motivator.
- Do not punish users for missing a day.
- Do not hide progress behind manipulative scarcity.
- Do not optimize only for time-on-site.
- Do not create shame-based leaderboards.
- Prefer mastery, autonomy, competence, and readiness over compulsion.

## MVP Gamification Features

- Daily 10-minute interview loop.
- Role readiness map.
- Concept challenge ladder.
- Streak with grace days, not punishment.
- Boss question after each concept cluster.
- Strong-answer portfolio.
- Session-end progress summary.
- Review campaign for interview date countdown.