Why.

An AI that doesn't grade wrong answers — it diagnoses the belief that caused them, then fixes it for good.

Comment

Inspiration

Every wrong answer a student writes is treated the same way by most tools: it's marked incorrect, and the correct steps are shown. But a wrong answer isn't random — it's the output of a belief that felt true at the moment it was written. A student who writes \((x+3)^2 = x^2+9\) hasn't been careless. They've correctly learned that multiplication distributes over addition, and generalized that rule one step too far. The error is logical, not sloppy — and no amount of "here's the right answer" fixes a belief that's still there, waiting to produce the same mistake on the next problem. I built Why to find that belief, name it, and dismantle it — not just correct the arithmetic sitting on top of it.

What it does

Why takes a photo (or typed transcription) of a student's actual wrong work, then:

  1. Transcribes it faithfully — including the mistakes, via GPT-5.6 vision — and lets the student confirm the transcription is accurate before anything else happens.
  2. Diagnoses the exact point of divergence — the specific line where the student's reasoning left the correct path — and infers the belief that made that step feel right, classified against a taxonomy of documented misconceptions (e.g. "the freshman's dream," illegal cancellation, sign errors).
  3. Shows, rather than tells — a parameterized interactive visualization (an area model, a number line, a fraction bar) built from the student's actual numbers, so the missing piece of their reasoning becomes visible, not just stated.
  4. Verifies the fix — three fresh problems, including one deliberately designed to tempt the old belief back, before marking the misconception cleared.
  5. Remembers — a private map of every misconception a student has ever had, cleared or active, with spaced re-checks so a fixed belief doesn't quietly erode.

The same diagnostic engine generalizes beyond algebra — geometry, fractions, exponents, basic statistics, physics, and chemistry — using a curated taxonomy where I've built it deep, and live GPT-5.6 reasoning (clearly labeled "reasoned live") everywhere else.

How I built it

I built Why with Codex, working in a single continuous session end to end. The stack: React/TypeScript frontend, Node/Express backend, SQLite for zero-setup persistence, and GPT-5.6 for every step of reasoning — vision transcription, misconception classification via structured JSON outputs, dynamic widget parameterization, and adaptive question generation.

Codex accelerated nearly every layer: the database schema and query layer, the diagnosis pipeline's typed request/response contracts with Zod validation, the full React component tree, the interactive SVG widgets, the responsive design pass across phone/tablet/desktop, and the regression tests confirming the taxonomy matcher and AI-response validators. Key decisions I made deliberately rather than accepting Codex's first pass: refusing any hardcoded or mocked diagnosis path (every result must come from a live model call), enforcing per-profile data isolation after catching a real cross-user data leak during testing, and holding the visual design to a strict "no AI aesthetic" brief — graph paper, graphite, one amber highlighter — so the product feels like a desk, not a dashboard.

Challenges I ran into

The hardest problem wasn't the AI call — it was making sure nothing in the pipeline was quietly faked. Early in development I caught myself accepting hardcoded diagnosis text for demo reliability; I went back and forced every path, including demo mode, through the real transcription-to-diagnosis pipeline, with honest error states instead of silent fallbacks. I also found and fixed a genuine data isolation bug, where two different user profiles were reading the same database rows — a serious bug to catch before judging, not after. Getting the interactive widgets to parameterize correctly from arbitrary student numbers (not just my test case) took real iteration, as did keeping the UI calm and legible on a 360px phone screen without losing the handwriting-page illusion that makes the diagnosis feel personal.

Accomplishments that I'm proud of

Getting from "AI marks your homework wrong" to "AI shows you the shape of your own mistake, in your own numbers, live" is a genuinely different product, not a feature bolt-on — and I'm proud that every part of that flow is real and running, not mocked for the demo. I'm also proud of the restraint in the design: nothing on screen says "AI," because the whole point is that this should feel like a quiet, patient tutor, not a tech product.

What I learned

The most reliable-feeling AI products aren't the ones with the most features — they're the ones that fail honestly. Every hour I spent building graceful error states (a blurry photo, a low-confidence diagnosis, an ambiguous subject) did more for the product's credibility than any new capability would have. I also learned, the hard way, that "it built it" and "it works" are different claims, and that catching a data isolation bug or a mocked response early is worth far more than shipping a flashier feature late.

What's next for Why.

Deepening the curated misconception taxonomy across all subjects to the same depth I reached in algebra, adding real teacher accounts so the seeded "Class view" becomes a genuine multi-student dashboard, and expanding the spaced-repetition recheck system so a cleared misconception is verified not just once, but on a schedule proven to build durable retention.

Built With

Share this project:

Updates