DEV Community

Cover image for Your README is probably bad. Let's find out. πŸ”₯
Rudra Malvankar
Rudra Malvankar

Posted on

Your README is probably bad. Let's find out. πŸ”₯

#devchallenge #hf26challenge #ai

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle Submission πŸ’Έ

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

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 (<!-- [TODO: ...] -->) 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:

GitHub logo RudraMalvankar / ReadMeRoast

ReadMeRoast πŸ”₯

Your README is probably bad. Let's find out. πŸ”₯

Hacktoberfest 2026 Model License: MIT Next.js 16

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…
View on GitHub

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.

Top comments (0)