Readme Writer

Review Procedure

When asked to review a README, follow these steps in order:

Step 1: Gather Project Context

Before touching the README, explore the codebase to understand the ACTUAL state:

1. Read the current README fully
2. Read package.json, pyproject.toml, requirements.txt, or equivalent for dependencies
3. Read the main entry point (e.g., app/main.py, src/index.ts)
4. Read config files (e.g., config.yaml, .env.example)
5. Check docker/ or docker-compose.yml for containerization setup
6. Check docs/ folder for existing documentation
7. Scan test files for feature coverage hints
8. Check CI/CD files (.github/workflows/) if present

Step 2: Audit Against Checklist

Compare the README against the quality checklist. Score each section as:

• Present & Accurate — Section exists and matches codebase
• Present but Outdated — Section exists but doesn't reflect current state
• Missing — Section should exist but doesn't
• N/A — Not applicable to this project

Step 3: Report Findings

Present a summary table:

| Section              | Status             | Notes                          |
|----------------------|--------------------|--------------------------------|
| Title & Description  | Present & Accurate |                                |
| Features             | Present but Outdated | Missing new collector X      |
| Installation         | Present & Accurate |                                |
| ...                  | ...                | ...                            |

Step 4: Apply Fixes

After presenting findings, apply all fixes directly to the README:

• Add missing sections in the standard order (see template reference)
• Update outdated content to match current codebase
• Fix broken commands by verifying against actual project setup
• Improve structure — consistent heading levels, proper code fences with language tags
• Add missing badges if the project has CI/CD, package registry, or license

Writing Standards

Formatting Rules

• Use ATX-style headers (# H1, ## H2) — never underline-style
• One blank line before and after headers
• Code blocks must have language tags (bash, python, etc.)
• Use tables for structured comparisons
• Use relative links for internal docs ([API Docs](docs/API.md))
• Keep lines under 120 chars where practical

Section Ordering

Follow this standard order (skip sections that don't apply):

1. Title + badges
2. One-line description
3. Screenshot/demo (if visual)
4. Features list
5. Architecture overview
6. Prerequisites
7. Installation
8. Configuration
9. Usage / Running
10. API reference (or link to docs/)
11. Testing
12. Deployment / Docker
13. Project structure
14. Contributing
15. Roadmap
16. License

Command Blocks

• Every command block must be copy-paste ready
• Include environment setup (e.g., cd project-dir, source venv/bin/activate)
• Show expected output where helpful
• Use platform-appropriate commands or note platform differences

Tone

• Direct and professional
• Second person ("You can...", "Run the following...")
• Active voice preferred
• No filler phrases ("In order to", "Basically", "Simply")

Common Issues to Catch

• Docker commands missing port mappings or environment variables
• Installation steps that skip dependency installation
• Config examples that don't match actual config schema
• API endpoints listed that don't exist (or missing ones that do)
• Features listed that aren't implemented
• Screenshots that don't match current UI
• Broken internal links
• Missing license section when LICENSE file exists
• Project structure that doesn't match actual file tree

Reference Files

• Quality Checklist — Section-by-section audit criteria
• README Template — Starter template for new READMEs