PlainSpeak — Paste the confusing. Get the clear.

Inspiration

Everyone has a "fine print" moment — a medical discharge note you nod along to, a freelance contract clause you sign without understanding, an academic abstract that's technically English. I kept watching smart people (myself included) either trust AI paraphrases blindly or give up entirely. I wanted a tool that doesn't just simplify text, but proves you actually understood it.

What it does

PlainSpeak turns dense text into plain language — then proves comprehension. Paste a confusing paragraph (or tap a built-in sample: medical, legal, academic), pick your audience (Age 12, Plain adult, or Professional), and hit Simplify. You get: the plain-language rewrite, 3 key takeaways, a before/after Flesch-Kincaid readability scorecard, and a 3-question quiz on the simplified text. Watching a grade level drop from "college graduate" to "middle school" — then acing the quiz — is the whole product in one beat.

How we built it

A Python/Flask app with vanilla HTML/CSS/JS — no build step, no framework. Live AI mode calls any OpenAI-compatible chat-completions endpoint with a strict JSON contract (simplified text + 3 takeaways + 3 quiz questions, server-side validated). Without a key, it runs in a clearly-labelled demo mode: a hand-written rule pipeline (sentence splitting, jargon dictionary) plus a keyword quiz — never pretending to be AI. Readability scores are computed locally with the Flesch formulas. Built with the Devpost Learn Skill Pack: the repo includes the skill-generated scope.md, prd.md, and spec.md planning docs. 44/44 pytest tests pass. MIT licensed.

Challenges we ran into

The honest-fallback problem: a demo mode that looks like AI is worse than no demo at all, so every demo output is labelled on screen and the rule pipeline is genuinely useful on its own. The other hard part was making the LLM return reliable structured output — solved with response_format: json_object plus strict server-side shape validation and a clean error path. And designing quiz questions that test comprehension rather than trivia turned out to be a real product decision, not just a prompt tweak.

Accomplishments that I'm proud of

The quiz-and-score loop: simplification you can verify, not just read
Honest demo modes — nothing ever presented as AI when it isn't
A complete, coherent product experience: one page, one flow, zero setup
44/44 tests passing across the server, LLM, fallback, and readability layers
Genuine skill-pack integration: interview → scope → PRD → spec → build, all in the repo ## What I learned I learned how to make an LLM return reliable JSON (response_format + server-side validation + a real error path instead of hope), how to design honesty into AI products (label everything), and that the "AI basics" that matter most are product decisions: what the AI may claim, what it must prove, and what happens when there's no key. I also learned the Flesch readability formulas are just counting — no AI needed. ## What's next for PlainSpeak PDF/DOCX upload, a saved library of simplifications, more languages (Hindi/Kannada), difficulty-adaptive quizzes, and a browser extension for "simplify this page."