Inspiration
Writing a good README is one of those things every developer knows they should do, but often rushes or skips entirely, especially during hackathons. I noticed that even solid projects get overlooked simply because their documentation is unclear or unpolished. Based on the theme of the hackathon "Hacks for Hackers", I thought, why build another product for the average non-technical user when I can ship a tool devs like me will come to love and appreciate, and also use. I then decided to build something that helps developers present their work better without forcing them to spend hours writing markdown instead of building.
What it does
README Doctor is a CLI tool built on the Gemini API that generates or refines GitHub READMEs. It supports two modes. Generate mode creates a complete README from structured project details. Polish mode takes an existing README and upgrades it into a concise, professional, hackathon ready version. The goal is to help developers communicate their project clearly, fast, and consistently.
How I built it
The tool is built in Python and uses the Gemini API for content generation. The codebase is modular, with separate files handling prompt design, generation logic, polishing logic, and API communication. The CLI entry point detects whether the user wants to generate a new README or polish an existing one and runs the appropriate pipeline. Prompts are carefully designed to return clean markdown output without extra explanations or filler text.
Challenges I ran into
One of the biggest challenges was prompt tuning. Early outputs were overly generic (verbose) and included meta commentary instead of clean README content. Another challenge was working under hardware constraints and avoiding SDK dependencies that required native compilation.
Accomplishments that i'm proud of
I am proud of building a fully working tool that solves a real problem developers face. The project supports two distinct workflows, produces consistent markdown output, and is easy to extend. I am also proud of shipping a complete project with clean structure, documentation, and a demo within the hackathon timeframe, as this is my first ever hack for a hackathon.
What I learned
This project reinforced the importance of prompt design, modular architecture, and building tools that developers actually want to use. I also gained deeper experience working with LLM APIs directly, handling edge cases, and designing CLI workflows that feel intuitive.
What's next for README Doctor
Next steps include adding README templates for different project types, improving customization options, and potentially adding a web interface. Long term, README Doctor could become part of a larger toolkit focused on improving developer documentation and project presentation.
Log in or sign up for Devpost to join the conversation.