Paste your README. Get a score. Get a better version.
This repo doesn't contain the source code for writebetterdocs.dev. It contains something more interesting: the complete specification that an AI built the site from.
writebetterdocs.dev is a README quality scorer. Paste any README, get a 10-point checklist score, and get an AI-powered rewrite of what's missing. It's brutalist on purpose — black, white, monospace, and a neon yellow highlighter. Color only appears when it means something.
The site was built entirely by AI from a single detailed prompt. That prompt is build-prompt.md.
Because the prompt is the source.
The code is generated output — like a compiled binary. The prompt is the human-readable spec that produced it. If you want to understand what the site does, how it looks, why every design decision was made, and how the AI scoring works — read the prompt. It's more useful than reading minified HTML.
This is also a bet on how software gets made now. A sufficiently detailed spec, given to a capable AI, produces a working product. The spec is the artifact worth versioning.
Every README is scored against these checks (all client-side, instant):
| # | Check | What it looks for |
|---|---|---|
| 1 | Clear title | Markdown H1 with content |
| 2 | One-line description | First non-heading line > 20 chars |
| 3 | Install instructions | Mentions install/setup/quickstart |
| 4 | Usage examples | Contains code blocks or usage section |
| 5 | Code block | Has at least one fenced code block |
| 6 | License | Mentions any license type |
| 7 | Contributing info | Mentions contributing/PRs/issues |
| 8 | Badges/status | Has shield.io or badge images |
| 9 | Not a stub | More than 200 characters |
| 10 | No TODOs left | No TODO/FIXME/TBD placeholders |
When your score is below 8/10, the site can generate an improved version of your README using Claude Sonnet. The AI is tightly scoped:
- Only rewrites READMEs (not a general chatbot)
- Keeps all existing content intact
- Adds only the missing sections with placeholder content you can customize
- Rejects non-README input
- Rate limited, max tokens capped, input size bounded
The system prompt is documented in full in build-prompt.md so you can see exactly what the AI is told to do. No black boxes.
- Brutalist. Black and white. No gradients, shadows, rounded corners, or transitions.
- Color is earned. Neon yellow (#E6F020) only appears as a highlighter on interactive elements. Red/green only appear in scores. Everything else is monochrome.
- Plain HTML. Single file, no framework, no build tools. The page itself weighs under 20KB.
- Privacy by default. Scoring is 100% client-side. No data leaves your browser unless you explicitly request an AI rewrite.
The prompt in build-prompt.md is complete enough to rebuild the site from scratch. Feed it to Claude, ChatGPT, or any capable model. You'll get a working single-file HTML app.
Or just use writebetterdocs.dev.
MIT
Made by @meimakes
