🧙 QuizWizz

project:     QuizWizz 🧙
type:        WordPress plugin (FOSS, GPLv2+)
one_liner:   Browser-playable multilingual quizzes from a verified English bank,
             AI used only to translate + to craft quizzes via a chat-bubble wizard.
platform:    {wp: "7.0 Armstrong", php: "8.5 (min 8.3)", db: "MySQL/MariaDB", react: 18}
 
principle:   DATASET-IS-TRUTH ▸ no fact-generation. AI scope = {batch_translate, chat_craft} only.
 
data_model:                                # native, no bloat
  cpts:      [quiz, question]              # custom post types
  taxes:     [subject, difficulty, language, tag]
  store:     question{stem, type, choices[], correct_idx, explanation, src, lang}
  note:      Uses PDO SQLite database (opentdb.sqlite) instead of wp_remote_get for zero-latency lookups
 
quiz_sources:
  primary:   OpenTDB (Bundled local SQLite DB, ultra-fast ORDER BY RANDOM() LIMIT, pre-translated swarm localization)
  big_bank:  TriviaQA (~95k)    # volume, human-authored, CC BY 4.0 (open-answer→1× distractor prep)
  academic:  Global-MMLU        # 42 langs PRE-translated, 57 subjects (skip translation!)
 
ai:
  gateway:   OpenRouter         # OpenAI-compatible /chat/completions, SSE streaming
  picker:    GET /api/v1/models?order=newest  # cache+refresh hourly → model dropdown
  selectable:[model, prompt]    # both user-editable, every call
  cost_ctrl: [":floor variant", "max_tokens cap", "BYOK", spend-limit]
  jobs:
    translate: batch job (WP-Cron) → store per-language question sets
    agent:     "Magical Quiz Wizz" floating chat bubble → NL input → quiz draft
  json:      response_format=json_schema  # reliable question objects
  key:       server-side only (wp-config/env) — NEVER client JS
 
play:                            # "on location, simply in browser"
  engine:    Alpine.js (~7kB, no build) renders + grades client-side
  data:      quiz JSON localized via wp_localize_script / REST
  resume:    localStorage (real plugin only; not in WP artifacts)
  modes:     [practice, timed, shuffle, Form-A/B/C]
 
output:
  print:     window.print() + @media print CSS  # zero-dep results sheet + answer key
  pdf_srv:   mPDF 8.3.1 (optional, for saved/emailed/non-Latin)
  share:     Web Share API (navigator.share) + Open Graph meta
 
admin:                           # most-genius WP 7.0 backend
  ui:        Data Views (filter/sort quizzes & questions, native 7.0)
  ability:   register quiz-gen as a WP Abilities API ability (plugs into 7.0 AI hub)
  settings:  @wordpress/components React page → /wp/v2/settings (show_in_rest)
  block:     dynamic block apiVersion 3 (embed quiz on any page)
 
security:    [cap_check → nonce → sanitize → ESCAPE, $wpdb->prepare(%s %d %i),
              "defined('ABSPATH')||exit", permission_callback on EVERY route,
              sanitize HTML before mPDF]
qa:          [Plugin Check (mandatory), PHPCS+WPCS, PHPUnit, 2FA on wp.org acct]
i18n:        __()/esc_html__() + .pot
 
milestones:
  m1: CPT + OpenTDB import + Alpine browser play + print sheet     # playable MVP
  m2: OpenRouter model-picker + batch translate + Data Views admin # multilingual + backend
  m3: "Magical Quiz Wizz" chat-bubble agent (NL→quiz) + share      # the magic
  m4: security pass + Plugin Check green → package/ship
 
non_goals:   [LMS/courses, payments, per-user accounts (v1), server-side grading]
foss_purity: OpenRouter = the ONLY SaaS dep; swap for LibreTranslate + Ollama/vLLM = 100% self-host
risks:       [MT loses culture→spot-check, distractor drift→re-validate,
              mPDF dated CSS→use print/headless-chrome, SSE buffering→non-stream fallback]

ROLE: Ruthless senior reviewer. MANDATE: make it perfectly do EXACTLY what the SPEC needs — nothing more.
 
SPEC (the only thing that matters):
  User picks {category(ies), count, difficulty, mode ∈ {online, print}, language}
  → a correct, valid quiz is produced, every time, on every edge case.
 
ARTIFACT UNDER REVIEW: <paste code / component / route / admin feature>
 
──────────────── THE LOOP (repeat each pass) ────────────────
1. ✂️ YAGNI SWEEP — for every field/feature/branch/dependency/abstraction:
     ask 3: (a) Required by SPEC *now*? (b) Does removing it break SPEC? (c) Cheaper to add later than carry now?
     → if NOT-required & doesn't-break & cheaper-later ⇒ CUT IT (log as ✂️). List all cuts first.
2. 🔍 SCAN the 8 LENSES — log EVERY issue found.
3. 🏷️ CLASSIFY each by severity (rubric below).
4. 🔧 FIX only the highest-severity batch — one concern at a time, smallest change.
5. ✅ VERIFY the fix + scan for regressions it introduced.
6. ↻ RE-RUN from step 1 on the changed artifact.
 
EXIT (stop, do NOT gold-plate) when ALL true:
  • 0 P0 and 0 P1 issues
  • YAGNI sweep finds nothing left to cut
  • every SPEC acceptance test passes (incl. edge cases)
 
──────────────── 8 LENSES ────────────────
✅ Correctness  edge cases: 0 results · count > pool · empty category · all-difficulties · mixed split · RTL/non-Latin lang · mode switch mid-build
🔒 Security     cap→nonce→sanitize→escape · count clamped SERVER-side · key never client-side · $wpdb->prepare(%s %d %i)
♿ A11y         keyboard-only · ARIA roles/labels · focus mgmt · contrast
📱 UX           states present (empty/loading/error/success) · mobile · one obvious action
⚡ Perf         no N+1 · pool-count & model-list cached · minimal payload
🧩 Simplicity   fewest moving parts · no dead code · no unused deps · no premature abstraction  ← YAGNI lives here
🌍 i18n         strings wrapped · translated data renders · fonts load
🚢 Ship         Plugin Check · WPCS · clear names · docblocks on public API
 
──────────────── SEVERITY ────────────────
P0 broken / insecure / data-loss      → fix immediately
P1 wrong on an edge case / SPEC gap   → fix this pass
P2 UX / perf friction                 → fix if cheap
P3 cosmetic polish                    → fix only if free
 
──────────────── OUTPUT EACH PASS ────────────────
1) ✂️ CUTS: bullet list of everything removed/deferred + why
2) ISSUE TABLE:  | # | Lens | Sev | Issue | Fix / ✂️CUT |
3) REVISED ARTIFACT: the diff (changed lines only)
4) VERDICT:  🔁 LOOP AGAIN  |  ✅ PERFECT (SPEC met · nothing to cut · all tests green)