# QC.md The checklist to run **before** calling anything finished. ## How to use this Quality control is a **separate job from building**. Don't ask for a QC pass in the same breath as "build me X" — the same AI that just built something is the worst possible judge of it. It already believes it did a good job. Start a fresh message, or better, a fresh conversation: ``` Run QC.md against what you just built. Go through every item. For each one, say PASS or FAIL and show me the evidence — the command you ran, the output you got, or the line of code you're pointing at. Do not fix anything yet. Report first. I'll decide what gets fixed. ``` Two rules that make the difference between a real QC pass and a fake one: - **Evidence, not claims.** "Tested, works fine" is not a pass. "Ran `bun test`, 8 passed, output below" is a pass. If there's no evidence, treat it as untested. - **Report before fixing.** If it fixes as it goes, you never find out how many things were wrong, and you can't tell which fix broke what. --- ## Part 1 — Design QC Run this on anything with a screen. ### Size and shape - [ ] Does it work at **375px** wide (a normal phone)? - [ ] Does it work at **768px** (tablet)? - [ ] Does it work at **1280px** (laptop)? - [ ] Does the page **ever scroll sideways**? It must not. Not at any width. - [ ] Do wide things — tables, code blocks, images — scroll *inside their own box* rather than pushing the page wide? - [ ] Does anything overlap or collide at any width? ### Readable - [ ] Body text at least **16px**. Smaller and phones zoom awkwardly. - [ ] Enough contrast between text and background to read in sunlight? - [ ] Line length comfortable — not stretched across a huge screen? - [ ] Does it work in **both light and dark mode**, if the site supports them? ### Touchable - [ ] Is everything tappable at least **44x44px**? - [ ] Are tap targets far enough apart to not hit the wrong one with a thumb? - [ ] Does anything rely on **hovering**? Phones can't hover. It must work without. ### Consistent - [ ] Same colors used for the same meanings throughout? - [ ] Spacing consistent, or are there random gaps? - [ ] Do links look like links? - [ ] Do images have **alt text** describing them? ### Honest - [ ] Is there any **placeholder text** left in? ("Lorem ipsum", "TODO", "Coming soon") - [ ] Do all the links actually go somewhere? Any dead ends? - [ ] Does anything claim to work that doesn't? A button that does nothing is worse than no button. --- ## Part 2 — Code QC Run this on anything that was written or changed. ### Did it do the job? - [ ] Does it do **exactly what was asked**? - [ ] Does it do **anything that wasn't asked**? Extra features count as failures here. - [ ] Does it actually **run**? Was it run, or only looked at? - [ ] Did anything that worked before **stop working**? ### Is it clean? - [ ] Any leftover debugging? (`console.log`, `print`, commented-out blocks) - [ ] Any code that isn't used any more? - [ ] Any copy-pasted chunks that should be one thing? - [ ] Is this the **simplest version** that works, or the cleverest? ### Is it safe? - [ ] Any **passwords, API keys, or secrets** written directly into the code? - [ ] Any real user data, email addresses, or personal details left in? - [ ] Were any **new packages installed**? Were they asked about first? - [ ] Did anything change **outside this project folder**? ### Will it survive? - [ ] Would someone else understand this in six months? - [ ] Would **you** understand it in six months? - [ ] If it broke at 2am, is there enough here to work out why? --- ## Part 3 — Bug hunt Building asks "does it work?" Bug hunting asks "**how do I break it?**" Those are different questions and they find different things. Go through these deliberately and actually try them. ### Bad input - [ ] What if a field is left **empty**? - [ ] What if someone types **way too much** — a 10,000 character name? - [ ] What if they type the **wrong kind of thing** — letters in a number field? - [ ] What if they paste in **emoji, quotes, or another alphabet**? - [ ] What if they paste in something that looks like **code**? ### Bad conditions - [ ] What if the **internet is slow**? (Browser dev tools can fake this.) - [ ] What if the internet **drops halfway through**? - [ ] What if the thing it's loading **doesn't exist**? - [ ] What if the server is **down**? ### Bad timing - [ ] What if someone **double-clicks** the button? Does it happen twice? - [ ] What if they hit **back** mid-way through? - [ ] What if they **refresh** while something is saving? - [ ] What if they open it in **two tabs** at once? ### Edges - [ ] What happens with **zero** items? Does the empty state look deliberate or broken? - [ ] What happens with **one** item? - [ ] What happens with **a thousand**? - [ ] What about the **first** time someone uses it, with nothing saved yet? ### When it breaks - [ ] Does the error message tell the person **what to do**, or just say "Error"? - [ ] Does it lose their work? - [ ] Does it leak anything technical it shouldn't show a stranger? --- ## The rules of a good QC pass 1. **Evidence or it didn't happen.** Every PASS needs something to point at. 2. **Report everything, fix nothing.** Fixes come after the full picture. 3. **Failing items are the valuable output.** A QC pass with zero failures usually means the checking was shallow, not that the work was perfect. 4. **A fresh pair of eyes finds more.** Ask a *different* AI, or at least a new conversation, to run QC on the first one's work. 5. **Re-run after fixing.** Fixes break things. That's not cynicism, it's just what happens. --- ## Quick version For small changes, when the full list is overkill: ``` Before you say this is done: 1. Show me it running. Not a description — the actual output. 2. Tell me what you changed that I didn't ask for. 3. Tell me what you're least confident about. 4. Tell me one way a user could break this. ``` Question 3 is the useful one. Asking an AI what it's *least sure about* gets you a much straighter answer than asking whether it's confident.