# Technical Specification (PRD): Wild Zebra — Adaptive Socratic AI Tutor for Kids (Grades 2–9)

- **Track:** Ask VC Launch #214 · Startup #1 (`wild-zebra` / `ai-kids-tutor`)
- **Access:** 100% Open Specification — **zero login and zero promo code required** to build locally.
- **Target Users:** Students in Grades 2–9 (ages 7–15) practicing Fractions, Pre-Algebra, and Reading Comprehension, plus Parents viewing weekly mastery cards.
- **North Star Metric:** Weekly Mastery Concepts Solved Without Direct Answer Leak (`WMCS >= 5/week`).

## 1. Core Product Problem (Why Standard Chatbots Fail on Attempt #1)
Generic single-shot chatbots immediately reveal the final answer (e.g., `"The answer is 1/2"`), turning the AI into a homework cheat tool, or hallucinate floating-point math steps. Parents cancel subscriptions within 14 days when children stop thinking independently.

## 2. Mandatory Functional Modules to Implement
1. **Deterministic Math & Fraction Misconception Engine (Exact Rational Arithmetic):**
   - Represent fractions as exact integer pairs `(numerator, denominator)` reduced by `gcd(a, b)` — never approximate with floats.
   - Detect classic student misconceptions before hinting:
     - **Case A (Denominator-Addition Trap):** Problem `1/3 + 1/6`, student writes `2/9` (added `1+1` and `3+6`). Tutor detects `num1+num2 / den1+den2`, explains visually why `2/9 < 1/3` cannot hold when adding a positive slice, and asks the student to convert `1/3` into sixths (`?/6 + 1/6`).
     - **Case B (Linear Equation Sign-Flip Trap):** Problem `3x - 7 = 14`, student writes `x = 7/3` (computed `14 - 7`). Tutor asks student to plug `7/3` back into `3x - 7` (`0 != 14`) and balance both sides by adding `7`.
2. **Reading Comprehension & Critical-Thinking Diagnostic Engine:**
   - **Case C (Correlation vs. Causation Passage):** Passage claims *"Cities with more public libraries have higher math scores, therefore building libraries automatically raises math scores."* Student answers *"Because libraries hold math books."* Tutor guides the student to spot a **confounding variable** (e.g., municipal education budget or household study support) and propose a fair comparison.
3. **3-Step Socratic Ladder (Hard Anti-Spoiler Gate):**
   - `Step 1 (Diagnose)`: Name the specific misconception gently without stating the final answer.
   - `Step 2 (Scaffold)`: Give a visual/concrete micro-question that unlocks the next step.
   - `Step 3 (Verify Mastery)`: Validate the student's revised answer deterministically and award a Mastery Concept badge + Parent Summary Card.
4. **Child Privacy & Safety Guardrails (COPPA / GDPR-K):**
   - Collect **zero** child full names, emails, phone numbers, geolocation, or voice/photo uploads. Store progress strictly under an anonymous session/nickname token in local storage or SQLite.

## 3. Recommended Local Architecture & Self-Tests
- **Single-command runnable MVP:** Provide an interactive web UI (`index.html` + `app.js` or local server) with a Grade/Subject switcher (**Math: Fractions**, **Math: Equations**, **Reading: Critical Logic**), interactive student attempt input, 3-step Socratic feedback card, Mastery Progress bar, and Parent Report preview.
- **Automated Verification Suite (`test_tutor.js` or `pytest`):**
  1. Assert `1/3 + 1/6` with attempt `2/9` flags `denominator_addition` and output string does **not** leak `= 1/2` on Hint #1.
  2. Assert `3x - 7 = 14` with attempt `7/3` flags `inverse_sign_error` and verifies `x = 7` on retry.
  3. Assert Reading passage attempt flags `correlation_vs_causation` and passes zero-XSS / zero-PII checks.
