Most GitHub projects fail not because of bad code, but because they were never products.

This tool analyzes a README and checks whether it contains the minimum signs of product thinking.

• Not success prediction
• Not AI magic
• Just a structured reality check

Quick Start

Try it online: https://nascherba71.github.io/readme-driven-product-validator/

(Enter your OpenRouter API key and paste your README to analyze)

What this tool does

Given a README.md (file path or repository URL), it evaluates:

• Is a real problem clearly stated?
• Is the target user identifiable?
• Is there a concrete value proposition?
• Is there a reason this should exist instead of alternatives?
• Is there at least a plausible path to monetization?

Output: a short, explainable report with flags and reasons.

Availability

Web Interface (No Installation Required)

Try the tool online at: https://nascherba71.github.io/readme-driven-product-validator

Simply:

1. Get your free API key from OpenRouter
2. Paste it into the web interface
3. Paste your README content
4. Click "Analyze README"
5. Download the report if needed

Command Line (Local Installation)

For advanced usage and automation, install locally (see Installation section below)

What this tool does NOT do

• ❌ It does NOT predict startup success
• ❌ It does NOT evaluate code quality
• ❌ It does NOT estimate market size
• ❌ It does NOT replace thinking

Example output

Problem statement: ❌ Target user: ⚠️ (too broad) Value proposition: ❌ Differentiation: ❌ Monetization path: ❌

Summary: This looks like a technical experiment, not a product.

Installation

Install the required dependencies:

pip install -r requirements.txt

Create a .env file with your OpenRouter API key:

cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

Get your free API key at OpenRouter.

Usage

Run the validator on any README file:

python validator.py path/to/README.md

Example:

python validator.py README.md

The tool will analyze the README and provide a report with flags indicating:

• ✅ Pass: Meets the criteria
• ⚠️ Warning: Partially meets the criteria
• ❌ Fail: Does not meet the criteria

Language Support

By default, reports are generated in English. To specify a different language, use the --language (or -l) flag:

# English report (default)
python validator.py README.md

# Russian report
python validator.py README.md --language ru
python validator.py README.md -l ru

Save Report to File

Use the --output (or -o) flag to save the report to a file:

# Save report to file (English, default)
python validator.py README.md --output report.txt

# Save report to file (Russian)
python validator.py README.md --language ru --output отчет.txt
python validator.py README.md -l ru -o отчет.txt

Batch Validation

Validate multiple repositories at once from various sources:

Validate from a File List

Create a text file with repository URLs (one per line):

# repos.txt
https://github.com/django/django
https://github.com/pallets/flask
owner/repo

Then run:

python validator.py --batch repos.txt --format csv --output report.csv

Scan an Awesome List

Extract and validate all repositories from an Awesome List markdown file:

python validator.py --scan-awesome awesome-python.md --format html --output report.html

Validate Organization Repositories

Validate all public repositories from a GitHub organization:

python validator.py --org microsoft --limit 20 --format json --output ms-repos.json

Search and Validate

Search GitHub and validate matching repositories:

# Search by topic and stars
python validator.py --search "topic:machine-learning stars:>1000" --limit 30

# Search by language
python validator.py --search "language:python topic:web-framework" --limit 20 --format html

Batch Options

• --batch, -b: Path to file with repository URLs (one per line)
• --scan-awesome: Path to Awesome List markdown file
• --org: GitHub organization name to scan
• --search: GitHub search query
• --limit: Maximum number of repositories to validate (default: 50)
• --format: Output format - text, csv, json, or html (default: text)
• --parallel: Number of parallel validations (default: 3, be mindful of rate limits)
• --github-token: GitHub token for higher API rate limits (optional)

Output Formats

Text (default): Human-readable console output

python validator.py --batch repos.txt

CSV: Spreadsheet-compatible format

python validator.py --batch repos.txt --format csv --output report.csv

JSON: Machine-readable format with full details

python validator.py --batch repos.txt --format json --output report.json

HTML: Interactive web report with charts and filtering

python validator.py --batch repos.txt --format html --output report.html

The HTML report includes:

• Summary statistics with visual charts
• Sortable and filterable results table
• Expandable details for each repository
• Export to CSV functionality

Automation

This repository includes a GitHub Action that automatically validates README changes on pull requests.

To enable it in your repository:

1. Copy .github/workflows/validate.yml to your repository
2. Add your OPENROUTER_API_KEY to repository secrets (Settings → Secrets and variables → Actions)
3. The validation will run automatically on PRs that modify README.md

If the API key is not set, the workflow will skip validation with a warning.

Template

Use the Product README Template to structure your README in a way that helps it pass validation. The template includes sections for:

• Problem Statement
• Target User
• Value Proposition
• Differentiation
• Monetization Path

Documentation

• Specification
• Contributing
• Our Story & Credits
• Examples
• Product README Template

Built With Collaboration

This project is the result of a partnership between product thinking and AI engineering. Read our full story of how we created this tool together in CONTRIBUTORS.md.

💡 NAScherba71 defined the vision. GitHub Copilot brought it to life. Together, we're helping developers validate product readiness.

All development is tracked transparently in our commit history.