Adaptive Difficulty, Session Rules, & Progression

Building this feature followed a strict, professional multi-layered software engineering lifecycle. By walking through these steps, we ensure code quality, keep business logic separated from the frameworks, and avoid bugs.

+------------------+     +------------------+     +------------------+     +------------------+
| 1. Requirements  | --> | 2. Specifications| --> | 3. TDD (Tests)   | --> | 4. Layered Code  |
| (The Idea)       |     | (The Spec Doc)   |     | (Write Tests 1st)|     | (Implementation) |
+------------------+     +------------------+     +------------------+     +------------------+
                                                                                    |
                                                                                    v
                                                                           +------------------+
                                                                           | 5. Verification  |
                                                                           | (Lint & Typecheck|
                                                                           +------------------+

1. Step 1: Requirements Gathering (The Idea): We started with a high-level user request detailing gameplay rules, retry loops, time bounds, and progression targets.
2. Step 2: Specification Design: Before writing any implementation code, we drafted specs/003-adaptive-difficulty/spec.md. This established our boundary conditions, edge cases, data structures, and functional requirements.
3. Step 3: Test-Driven Development (TDD): We wrote the unit tests first (e.g., adaptive-selector.test.ts) to verify selection ratios, retry states, and report calculations.
4. Step 4: Layered Implementation:
   • Domain Layer (Shared): Framework-free TypeScript containing the state machine for the selector, scoring, and badges.
   • Presentation Layer (Phaser/Angular): Phaser coordinates drawing answer wave physics, projectile impacts, and session timer ticks. Angular manages dialog overlays, badge listings, and parents' settings.
   • Data Layer (Firebase): Firestore Cloud Functions store unlocked badges and session results.
5. Step 5: Verification & Pre-Flight Check: Running static analysis (pnpm lint, pnpm typecheck) and integration test validations before deployment.

The original feature request that initiated this software cycle was as follows:

To guide the AI coding assistant accurately without ambiguity, we broke down the request into concrete specifications inside our feature workspace:

Functional Requirements

• FR-AD-001: System MUST track player correctness per question during a session, classifying questions into correctPool and incorrectPool.
• FR-AD-002: System MUST select questions from the incorrectPool at a 3:1 ratio (75% probability) relative to the correctPool when both are populated.
• FR-AD-003: System MUST display visual mistake feedback containing the complete equation (e.g., 6 x 7 = 42) when a player answers incorrectly or misses.
• FR-AD-004: System MUST trigger an immediate quick retry of the failed question (re-spawning the answer blocks) up to 2 times.
• FR-AD-005: System MUST display a 10-minute countdown timer in the top-right corner of the HUD.
• FR-AD-006: System MUST trigger a break reminder and pause gameplay when the timer reaches 0:00.
• FR-AD-007: System MUST generate a performance report modal showing incorrect answers and recommendations upon session completion.
• FR-AD-008: System MUST support unlockable badges (streak_master, hero_10_min) and save them to the player profile in Firestore.
• FR-AD-009: System MUST position left and right panels with a 10% margin on the left/right edges in desktop mode to keep HUD elements closer to the centered gameplay panel.

Crucial Edge Cases Addressed

1. Empty Pools on Boot: When the session starts, both correct/incorrect pools are empty. The selector falls back to the general eligible questions to prevent crash or locks.
2. Graceful Timer Interrupts: If the 10-minute timer ticks down to 0 mid-question, the system waits for you to finish answering that question before interrupting with the break modal.
3. Quick Retry Retaining: Answering correctly on a quick retry awards points, but does NOT move the fact out of the incorrect pool. This ensures it is queued for future sessions until mastered in standard gameplay rounds.

Think of these new features as a personal math coach standing next to you while you play:

+-----------------------------------------------------------------+
|                       1. THE MEMORY DECK                        |
|                     (Adaptive Selector)                         |
|  * Places correct answers in a "mastered" pile.                 |
|  * Places wrong answers in a "needs practice" pile.             |
|  * Draws from the practice pile 75% of the time.                |
+-------------------------------+---------------------------------+
                                | (Spawns targeted question)
                                v
+-----------------------------------------------------------------+
|                       2. THE INSTANT REPLAY                     |
|                    (Mistake & Retry Loop)                       |
|  * Shows the full equation immediately: "6 x 7 = 42".           |
|  * Drops the same question again so you can try it right away.  |
+-------------------------------+---------------------------------+
                                | (Checks duration & limits)
                                v
+-----------------------------------------------------------------+
|                       3. THE PRACTICE ALARM                     |
|                     (Timer & Break System)                      |
|  * Counts down from 10 minutes.                                 |
|  * Suggests a screen break, then gives you a performance report.|
+-----------------------------------------------------------------+

How the Code Executes Under the Hood:

• The Adaptive Selector: Referees select questions using adaptive-selector.ts. It enforces a 75% bias towards the incorrectPool and uses lastPlayedAtMs to pull the least-recently practiced facts first.
• Instant Correction & Quick Retries: When an answer is missed, the Phaser engine stops the falling physics, triggers a screen flash, and displays the correct equation. It immediately queues the same question round with wasQuickRetry = true.
• Session Controls: The Angular host tracks a countdown timer in gameplay-session.ts, updating every second and flagging the scene when the session expires.
• Close the Loop (Reports & Badges): Completing a session evaluates milestones. If your連勝 streak exceeds 10, the cloud function awards the streak_master badge.