README Doctor

Diagnose README problems, analyze reference styles, and prescribe improvements.

Diagnosis Process

Patient (README) Intake → Diagnosis → Prescription → Treatment

Mode 1: Diagnose & Treat (Default)

Diagnose current project's README and prescribe improvements.

Step 1: Intake

# Check current README
[ -f README.md ] && cat README.md

# Gather project info
[ -f package.json ] && cat package.json | jq '{name, description, version}'
[ -f pyproject.toml ] && grep -E "^(name|version|description)" pyproject.toml

Step 2: Diagnosis Checklist

Item	Diagnosis Criteria
Title	Is the project name clear?
Description	Does it explain "what & why" in 1-2 sentences?
Installation	Can anyone follow it?
Usage	Is there a runnable example?
Context	Is necessary background provided?
Structure	Does it follow cognitive funneling (broad → specific)?
Freshness	Does content match current project state?

Step 3: Prescription Output

## Diagnosis Results

### Healthy
- [x] Installation section exists
- [x] License stated

### Needs Attention
- ⚠️ Description too long (3 lines → 1-2 recommended)
- ⚠️ No usage example

### Needs Treatment
- ❌ Title only says "Project" → Change to actual name
- ❌ Install command outdated (npm install → npm i recommended)

## Prescription

### 1. Fix Title
- Current: `# Project`
- Recommended: `# my-awesome-tool`

### 2. Shorten Description
- Current: "This project is... (3 lines)"
- Recommended: "CLI tool for X. One-liner."

### 3. Add Usage Example
\`\`\`bash
my-tool --input file.txt --output result.json
\`\`\`

Mode 2: Reference Analysis

Analyze style from user-provided reference READMEs.

Input Formats

# GitHub URL
"Analyze https://github.com/vercel/next.js/blob/canary/README.md"

# Local file
"Analyze ~/projects/example/README.md"

# Direct paste
"Analyze this README style: [paste content]"

Analysis Items

Category	What to Analyze
Structure	Section order, hierarchy
Style	Badges, emojis, code blocks
Tone	Formal/casual, concise/verbose
Format	Tables, lists, blockquotes usage

Analysis Result Example

{
  "structure": ["Title", "Badges", "Description", "Features", "Install", "Usage", "Contributing", "License"],
  "styles": {
    "badges": true,
    "emoji_in_headers": false,
    "code_blocks": ["bash", "typescript"],
    "images": false,
    "toc": false
  },
  "tone": "professional-concise",
  "avg_section_length": "short"
}

Mode 3: GitHub Pattern Analysis

Extract README patterns from user's GitHub repositories.

# Analyze user repos
gh repo list <username> --limit 10 --json name,url

# Fetch README
gh api /repos/<owner>/<repo>/readme --jq '.content' | base64 -d

Extract common patterns from at least 3 READMEs.

Mode 4: Best Practices Check

Evaluate README quality based on references/best-practices.md.

Required Checks

• Title + one-liner description
• Installation method
• Usage example
• License

Recommended Checks

• Badges (npm version, license, etc.)
• Contributing guide
• Changelog link

Using References

When user provides a reference:

1. Analyze Reference → Extract style/structure
2. Diagnose Current Project → Identify issues
3. Prescribe → Suggest improvements in reference style

User: "Make my README like Vercel's style. Reference: https://github.com/vercel/next.js"

Process:
1. Fetch Vercel's README
2. Analyze: badges at top, concise sections, professional tone
3. Diagnose current README
4. Prescribe: "Add badges section", "Shorten description to 1 line", "Add Features table"

Templates

Project type templates in templates/ folder:

Template	Use For
templates/oss.md	Open source
templates/personal.md	Personal projects
templates/internal.md	Internal tools
templates/xdg-config.md	Config files

References

File	Content
references/best-practices.md	README best practices
references/section-checklist.md	Section checklist
references/templates.md	Language-specific patterns

Usage Examples

# Diagnosis request
"Fix my README"
"Diagnose this README"

# Reference-based
"Make README like this: https://github.com/facebook/react"
"Change to this style: [README content]"

# GitHub pattern
"Create README based on my GitHub style"
"Make README matching my other projects"

# New project
"I need a README for a new CLI tool"

Prerequisites

• gh CLI (for GitHub pattern analysis)
• jq (for JSON processing)
• Python 3.6+ (for running scripts)