{"slug": "your-readme-is-probably-bad-let-s-find-out", "title": "Your README is probably bad. Let's find out. 🔥", "summary": "A developer built ReadMeRoast, an open-source tool that audits public GitHub repository READMEs using Google's open-weight Gemma 2 model (gemma-2-27b-it), scoring documentation health across seven dimensions and generating a constructive critique plus a rewritten README. The tool pulls project facts from the repo and inserts explicit TODO placeholders for missing details rather than inventing commands or APIs, and it runs through Google AI Studio or Groq with local Ollama/vLLM fallback. It was submitted to the Hacktoberfest Open-Source AI Challenge Week 2 and released under the MIT License.", "body_md": "*This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle](https://dev.to/challenges/hacktoberfest-week2-2026-10-12)*\n\n## \n  \n  \n  What I Built\n\n**ReadMeRoast** is a developer tool and open-source documentation auditor built for the **Hacktoberfest Open-Source AI Challenge (Week 2: Side Hustle)**. \n\nIt 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.\n\n### \n  \n  \n  The Problem It Solves\n\nGreat open-source repositories often struggle to gain adoption because of poor documentation:\n\n1. \n**Decorative Badge Overload** : 20 status badges at the top, but no clear installation instructions.\n2. \n**The \"Curse of Knowledge\"** : Authors assume newcomers already understand runtime dependencies, ports, and configuration.\n3. \n**Archaeological Expeditions** : Finding out how to run or import a project requires digging through source code.\n\n### \n  \n  \n  Core Features\n\n- \n**7-Dimension Documentation Health Audit** : Evaluates*Clarity, Documentation Completeness, Setup & Installation, Usage, Examples, Visual Presentation, and Developer Experience* .\n- \n**Constructive, Savage Roasts** : Unvarnished, humorous developer critique targeting documentation shortcomings, never the person.\n- \n**Prioritized Action Plan** : High-ROI, numbered recommendations showing developers exactly what to fix first.\n- \n**On-Demand Zero-Hallucination Rewrite** : Gemma restructures verified project facts and inserts clear developer placeholders (`<!-- [TODO: ...] -->` ) for missing items without inventing fake commands or APIs.\n- \n**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.\n\n## \n  \n  \n  Demo\n\nExperience ReadMeRoast live:\n\n### \n  \n  \n  How To Try It:\n\n1. Paste any public GitHub repository URL (e.g. `https://github.com/facebook/react` or`https://github.com/vercel/next.js` ).\n2. Review your score, read the roast, and inspect the health matrix.\n3. Click **\"Fix My README\"** to generate the improved Markdown side-by-side with live line numbers and copy or download the file.\n\n## \n  \n  \n  Code\n\nReadMeRoast is 100% open source under the MIT License:\n\n# ReadMeRoast 🔥\n\n**Your README is probably bad. Let's find out. 🔥**\n\n**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.\n\n## ⚡ The Problem & Solution\n\nMost developer documentation suffers from three fatal problems:\n\n1. \n**Decorative Badge Bloat** : Badges and status shields take up screen space while installation commands are omitted.\n2. \n**Archaeological Discovery** : Discovering how to actually run or import a package requires digging through source files.\n3. \n**The \"Curse of Knowledge\"** : Authors assume contributors already understand runtime dependencies and environment setup.\n\n**ReadMeRoast solves this in 10 seconds:**\n\n- \n**Paste a public GitHub repo URL** — no signups, no auth tokens, no…\n\n \n \n## \n  \n  \n  How I Built It\n\nReadMeRoast is architected around open-weight AI, serverless route handlers, and strict defensive data parsing:\n\n### \n  \n  \n  1. The AI Engine (Gemma 2)\n\n- \n**Model** : Google's open-weight**Gemma 2 (`gemma-2-27b-it`)** , accessed through Google AI Studio / Groq with pluggable local fallback support (Ollama / vLLM).\n- \n**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` ).\n- \n**Strict Schema Enforcement** : Responses are validated and clamped through**Zod schemas** to guarantee valid JSON and prevent malformed UI states.\n- \n**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.\n\n### \n  \n  \n  2. Full-Stack Tech Stack\n\n- \n**Framework** : Next.js 16 (App Router) with React 19 and TypeScript.\n- \n**Styling** : Tailwind CSS v4 with custom dark mode variables, subtle grid backgrounds, and restrained developer-tool typography.\n- \n**Data Ingestion** : GitHub REST API v3 for decoding base64 README contents, metadata, stars, forks, and languages without cloning repositories.\n- \n**Markdown Rendering** :`react-markdown` with`remark-gfm` for tables, badges, and code blocks.\n- \n**Confetti Engine** :`canvas-confetti` triggered when repositories achieve a score of 80+/100.\n\n## \n  \n  \n  Why Does Open Innovation Matter?\n\nOpen-weight models like **Gemma 2** empower individual builders and open-source communities in ways closed proprietary APIs cannot:\n\n- \n**Freedom from Vendor Lock-In** : With open weights, developers control their roadmap without fear of sudden price hikes, deprecated endpoints, or arbitrary API restrictions.\n- \n**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.\n- \n**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.\n\n## \n  \n  \n  My Agent Session\n\nReadMeRoast was designed and implemented using an autonomous AI pair-programming workflow:\n\n- \n**Architecture & UI Design** : Built from scratch using modern developer-tool conventions inspired by GitHub, Linear, and Vercel.\n- \n**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.\n- \n**Automated Verification** : Created an end-to-end verification suite covering URL parsing, Zod contract clamping, and fallback states.\n\n## \n  \n  \n  My First User\n\nI shared ReadMeRoast with fellow open-source contributors getting their projects ready for Hacktoberfest:\n\n*\"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.\"*\n\n— **Beta Tester**\n\nBy combining humorous critique with an instant, ready-to-ship fix, ReadMeRoast turns tedious documentation maintenance into a 30-second win.\n\n## \n  \n  \n  Prize Categories\n\n- \n**Gemma** : Gemma 2 is used as the core open-weight AI model for README analysis and improvement.\n- \n**Render** : ReadMeRoast is deployed and publicly accessible through Render.", "url": "https://wpnews.pro/news/your-readme-is-probably-bad-let-s-find-out", "canonical_source": "https://dev.to/rudramalvankar/your-readme-is-probably-bad-lets-find-out-1iio", "published_at": "2026-10-18 15:44:27+00:00", "updated_at": "2026-10-18 15:47:39.830866+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models", "generative-ai", "ai-products"], "entities": ["ReadMeRoast", "Google", "Gemma 2", "Groq", "Ollama", "vLLM", "GitHub", "Hacktoberfest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-readme-is-probably-bad-let-s-find-out", "markdown": "https://wpnews.pro/news/your-readme-is-probably-bad-let-s-find-out.md", "text": "https://wpnews.pro/news/your-readme-is-probably-bad-let-s-find-out.txt", "jsonld": "https://wpnews.pro/news/your-readme-is-probably-bad-let-s-find-out.jsonld"}}