# Your README is probably bad. Let's find out. 🔥 > Source: > Published: 2026-10-18 15:44:27+00:00 *This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle](https://dev.to/challenges/hacktoberfest-week2-2026-10-12)* ## What I Built **ReadMeRoast** is a developer tool and open-source documentation auditor built for the **Hacktoberfest Open-Source AI Challenge (Week 2: Side Hustle)**. It takes any public GitHub repository URL, audits its `README.md` using Google's open-weight **Gemma 2** model, calculates an objective documentation health score across 7 key pillars, delivers a witty and constructive roast, pinpoints exact documentation gaps, and provides an on-demand, zero-hallucination improved README that developers can immediately ship. ### The Problem It Solves Great open-source repositories often struggle to gain adoption because of poor documentation: 1. **Decorative Badge Overload** : 20 status badges at the top, but no clear installation instructions. 2. **The "Curse of Knowledge"** : Authors assume newcomers already understand runtime dependencies, ports, and configuration. 3. **Archaeological Expeditions** : Finding out how to run or import a project requires digging through source code. ### Core Features - **7-Dimension Documentation Health Audit** : Evaluates*Clarity, Documentation Completeness, Setup & Installation, Usage, Examples, Visual Presentation, and Developer Experience* . - **Constructive, Savage Roasts** : Unvarnished, humorous developer critique targeting documentation shortcomings, never the person. - **Prioritized Action Plan** : High-ROI, numbered recommendations showing developers exactly what to fix first. - **On-Demand Zero-Hallucination Rewrite** : Gemma restructures verified project facts and inserts clear developer placeholders (`` ) for missing items without inventing fake commands or APIs. - **Interactive Developer UI** : Linear/Vercel-inspired dark theme, circular SVG gauges, side-by-side code editor with line numbers, and instant one-click copy and`.md` export. ## Demo Experience ReadMeRoast live: ### How To Try It: 1. Paste any public GitHub repository URL (e.g. `https://github.com/facebook/react` or`https://github.com/vercel/next.js` ). 2. Review your score, read the roast, and inspect the health matrix. 3. Click **"Fix My README"** to generate the improved Markdown side-by-side with live line numbers and copy or download the file. ## Code ReadMeRoast is 100% open source under the MIT License: # ReadMeRoast 🔥 **Your README is probably bad. Let's find out. 🔥** **ReadMeRoast** is a focused developer tool built for the **Hacktoberfest Open-Source AI Challenge (Week 2: Side Hustle)**. It analyzes public GitHub repository READMEs using an open-weight **Gemma 2** model, scores documentation health across 7 key dimensions, delivers a hilarious yet constructive roast, identifies documentation blindspots, provides actionable fixes, and generates a zero-hallucination rewritten README in one click. ## ⚡ The Problem & Solution Most developer documentation suffers from three fatal problems: 1. **Decorative Badge Bloat** : Badges and status shields take up screen space while installation commands are omitted. 2. **Archaeological Discovery** : Discovering how to actually run or import a package requires digging through source files. 3. **The "Curse of Knowledge"** : Authors assume contributors already understand runtime dependencies and environment setup. **ReadMeRoast solves this in 10 seconds:** - **Paste a public GitHub repo URL** — no signups, no auth tokens, no… ## How I Built It ReadMeRoast is architected around open-weight AI, serverless route handlers, and strict defensive data parsing: ### 1. The AI Engine (Gemma 2) - **Model** : Google's open-weight**Gemma 2 (`gemma-2-27b-it`)** , accessed through Google AI Studio / Groq with pluggable local fallback support (Ollama / vLLM). - **Isolated Service Layer** : AI logic is isolated behind a clean abstraction boundary (`lib/ai/client.ts` ,`lib/ai/analyze-readme.ts` ,`lib/ai/improve-readme.ts` ). - **Strict Schema Enforcement** : Responses are validated and clamped through**Zod schemas** to guarantee valid JSON and prevent malformed UI states. - **Zero Token Waste (On-Demand Generation)** : The initial repository audit uses only a single analysis prompt. The complete README rewrite is generated**only when the user clicks the "Fix My README" button** , preventing wasteful background API calls. ### 2. Full-Stack Tech Stack - **Framework** : Next.js 16 (App Router) with React 19 and TypeScript. - **Styling** : Tailwind CSS v4 with custom dark mode variables, subtle grid backgrounds, and restrained developer-tool typography. - **Data Ingestion** : GitHub REST API v3 for decoding base64 README contents, metadata, stars, forks, and languages without cloning repositories. - **Markdown Rendering** :`react-markdown` with`remark-gfm` for tables, badges, and code blocks. - **Confetti Engine** :`canvas-confetti` triggered when repositories achieve a score of 80+/100. ## Why Does Open Innovation Matter? Open-weight models like **Gemma 2** empower individual builders and open-source communities in ways closed proprietary APIs cannot: - **Freedom from Vendor Lock-In** : With open weights, developers control their roadmap without fear of sudden price hikes, deprecated endpoints, or arbitrary API restrictions. - **Local & Air-Gapped Privacy** : While ReadMeRoast currently analyzes public repositories, open-weight models allow teams to self-host the service on internal private infrastructure (via Ollama or vLLM) to audit proprietary codebases without sending documentation to third parties. - **Predictable, Cost-Effective Scale** : Open-weight innovation democratizes advanced AI capabilities, allowing solo indie hackers to build production-grade developer utilities at near-zero marginal cost. ## My Agent Session ReadMeRoast was designed and implemented using an autonomous AI pair-programming workflow: - **Architecture & UI Design** : Built from scratch using modern developer-tool conventions inspired by GitHub, Linear, and Vercel. - **Strict Zero-Hallucination Testing** : Validated against real repositories with varying documentation quality (`facebook/react` ,`vercel/next.js` , and minimal repos) to test truncation, error fallbacks, and schema recovery. - **Automated Verification** : Created an end-to-end verification suite covering URL parsing, Zod contract clamping, and fallback states. ## My First User I shared ReadMeRoast with fellow open-source contributors getting their projects ready for Hacktoberfest: *"I ran my CLI library through ReadMeRoast and it roasted me for having 12 status badges and literally zero install commands for Windows users. The score was a humbling 64/100, but clicking 'Fix My README' gave me an organized Quick Start section with copyable npm commands. I merged the rewrite right away."* — **Beta Tester** By combining humorous critique with an instant, ready-to-ship fix, ReadMeRoast turns tedious documentation maintenance into a 30-second win. ## Prize Categories - **Gemma** : Gemma 2 is used as the core open-weight AI model for README analysis and improvement. - **Render** : ReadMeRoast is deployed and publicly accessible through Render.