docs: bootstrap tutor planning

docs/planning/GAMIFICATION.md

@@ -0,0 +1,166 @@
+# 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.