MindZen

Inspiration

Every quiz app we've used scores one thing: did you get it right. That misses the part people actually struggle with. Almost everyone has had the experience of solving something easily on a quiet afternoon and then falling apart on the same problem in an exam hall, an interview, or a live coding round — clock running, someone watching. The knowledge didn't disappear. Something else did.

We wanted to build a platform that measures that second thing directly, and then does something useful with the answer instead of just printing a number. Hence the name: mind for intelligence, zen for clarity and calm. Half game, half consultation.

What it does

MindZen is a terminal platform that gives you brainstorming games and critical-thinking problems, measures how your thinking holds up under pressure, and then debriefs you like a coach would.

A session runs in three phases:

Stillness — six items, generous clocks, no interruptions. This is your baseline. Calm Room — guided box breathing between the phases. Nothing is scored here, on purpose. Storm — six more items, the clock cut by 45%, with distraction lines and score pressure ("another player just passed your score", "this item is worth double"). Debrief — three scores, a Zen level, and a written consultation.

Six games cover different kinds of thinking: Sequence Sight (pattern rules), Clean Reasoning (bat-and-ball, Wason selection, syllogism traps), Held in Mind (digit and word spans shown briefly then hidden), Interference (the obvious reading is wrong — "how many LETTERS in SEVEN?"), Number Rush (mental arithmetic), and Sideways (lateral riddles). Every session touches all six before repeating any.

You get three scores rather than one:

Intellect — difficulty-weighted accuracy. What you can solve. Clarity — clock margin on correct answers, pacing consistency, and the absence of snap-guessing and freezing. How cleanly you solve it. Calm — how much of your Stillness accuracy survives the Storm. What is left of you under load.

These combine into a MindZen Index (0–1000) that maps to six Zen levels: Dust → Pebble → Ripple → Bamboo → Lotus → Still Water. Each carries a description, a mantra, and a concrete next step.

Then the consultation engine reads your profile and writes a debrief: what it noticed in your telemetry (freeze rate, snap-guess rate, pacing swings, the calm-vs-storm accuracy gap, which specific skills fell below 50), and a plan targeted at your weakest dimension. Low Intellect gets method and notebook work. Low Clarity gets impulse control — two-pass reading, a forced three-second delay. Low Calm gets recovery training — box breathing, the physiological sigh, a one-item horizon after a miss. A balanced profile gets harder conditions instead of more repetitions.

Profiles persist, so you get a progress chart, a trend line, and a leaderboard across sessions.

How we built it

Pure Python 3.10+, standard library only — no dependencies, no install step, runs anywhere Python does.

The architecture keeps the four concerns strictly separate, which is what made the scoring tunable:

games.py and problems.py — the games and the content bank. Games are dumb and reusable: each one just returns an Attempt. scoring.py — takes a list of Attempt records and produces a Report. This is the only place the model lives. consult.py — takes a Report and produces language. Knows nothing about games or input. profile.py — JSON persistence, history, trend and leaderboard. ui.py — console I/O with hard-timed input, using select() on POSIX with a graceful fallback elsewhere.

The piece that made everything else possible is BotIO, a simulated player in ui.py parameterised by skill and composure. It plays full sessions head-lessly, which meant we could calibrate the scoring curve empirically — run six player archetypes across eight seeds each and check the six Zen levels actually spread out — instead of guessing at weights and hoping.

Challenges we ran into

The scoring model was wrong twice, in ways that only showed up under simulation.

The first version rewarded speed regardless of correctness, so a player who answered instantly and badly scored high on Clarity. We fixed it by making wrong and timed-out items contribute exactly zero clock margin, so speed can only ever be credited on items you actually got right.

The second bug was subtler and more interesting. Calm was computed as retention — pressure accuracy divided by baseline accuracy. But a player who failed everything in both phases has a retention of 1.0, and was being scored as serene. Failing equally in both phases is not composure. We now shrink retention toward the baseline (retention × (0.5 + 0.5 × baseline_accuracy)), blend it with raw pressure performance, and gate the pacing-stability terms behind a grounding factor so steady pacing with no output earns almost nothing. Both fixes are locked in by named tests.

Calibration. Our first working model gave a deliberately weak bot an index of 643 — Bamboo, a level it had no business reaching. Everything bunched into two tiers. Getting the six levels to actually discriminate took several rounds of simulate-adjust-simulate.

Timed input in a terminal is genuinely awkward. You can't kill a thread blocked on input(). We went with select() on stdin for POSIX and a measured-elapsed fallback for Windows and non-tty stdin, which also keeps the demo mode and the test suite working.

Tone. A tool that tells someone their "calm" score is low is doing something delicate. Rewriting the consultation text so it reads as coaching rather than judgement took as many passes as the scoring did.

Accomplishments that we're proud of The model is honest about the two ways it could be gamed, and both are closed and tested: speed without correctness buys no Clarity, and uniform failure scores low on Calm rather than high. Calibration by simulation. Six archetypes from struggling to master land cleanly across Pebble, Ripple, Bamboo, Lotus and Still Water in the right order. The levels mean something. 24 tests covering all of it — scoring edge cases, level boundaries with no gaps, answer normalisation, persistence round-trips, and a content test that verifies every stated answer passes its own checker. The consultation is specific, not generic. It cites your actual numbers back to you and prescribes for your particular weak point. Zero dependencies. Clone and run. We kept the responsible framing in. Every report ends with a clear statement that MindZen is a training and self-reflection tool, not a clinical test or a diagnosis, and that persistent difficulty with stress, focus or mood deserves a conversation with a qualified professional. Building something that looks like a psychological instrument came with an obligation to be loud about what it isn't. What we learned

The biggest lesson was that a metric you can't simulate is a metric you can't trust. Both scoring bugs were invisible from reading the formula and obvious after twenty simulated sessions. Building the bot player felt like a detour at the time; it turned out to be the most valuable hour of the project.

We also learned how much of measurement is about what you refuse to collapse. The temptation is always to ship one number. But the whole insight of MindZen lives in the gap between Stillness and Storm — average them into a single score and the finding disappears.

On the domain side: the interference and lateral items taught us that the hardest problems to write are the ones where the wrong answer is more attractive than the right one. And separating the games from the scoring from the language meant that when the model changed twice, nothing else had to.

What's next for MindZen A web and mobile front end. The core is already UI-agnostic — BotIO proved the engine runs with no terminal at all — so the games, scoring and consultation drop straight into a Flask or FastAPI layer. Adaptive difficulty. Right now items are sampled evenly. Next is a per-skill model that finds your ceiling and keeps you just under it, where learning is fastest. Longitudinal insight. With enough sessions we can say things a single session can't: whether your Calm is genuinely improving or whether you just had a good day, and whether the prescriptions are actually working. A real stress layer. Optional live opponents, a visible ticking clock, and leaderboard pressure in real time — closer to the conditions people actually break under. Validation. The dimensions are principled but not psychometrically validated. Running the interference and span tasks against established instruments would tell us how much of what we measure is real. A guided mode for the lower levels. Players at Dust and Pebble currently get a plan; they should get a structured multi-week programme with the Calm Room built into it. Expanded content, including community-submitted problems with a review path.