/validate-readme

Validate README

Activated Agent

Activate: readme-author agent

The agent will audit your README.md against Personal minimal standards.

Objective

Validate existing README.md structure and content against 8-section minimal requirements, identify missing or incomplete sections, and provide actionable recommendations for improvement.

Command Parameters

Parameter	Options	Default	Description
--tier	prototype, mvp, production	Auto-detect	Project tier to validate against
--format	console, markdown	console	Output format (console display vs. report file)
--output	<path>	./reports/readme-validation-report.md	Custom report path (requires --format=markdown)

Examples:

/document-generator:validate-readme                        # Console output, auto-detect tier
/document-generator:validate-readme --tier=mvp --format=markdown
/document-generator:validate-readme --format=markdown --output=./docs/readme-validation.md

Activated Skills

The agent will activate these skills:

1. readme-standards - minimal README validation criteria
2. readme-authoring - Reference templates for comparison

Process

The agent will follow this workflow:

1. Pre-flight Checks

Check if README.md exists:

• If README.md not found in current directory:

  ❌ No README.md found in current directory.
  
  Use `/document-generator:generate-readme` to create one.
  
  Aborting validation.
  

  • Stop execution

• If README.md exists: Proceed with validation

2. Detect Project Tier

Agent will detect project tier (if not specified via --tier) and display for user. Validation will use tier-appropriate standards from readme-standards skill.

3. Parse README Structure

Read and analyze README.md:

1. Extract sections - Identify which of the 8 sections are present (with flexible section names):

   • Title & One-Liner (check for # {Title} and description)
   • Badges Block (check for shield.io badges or similar)
   • Short Description (## Description or ## Overview acceptable)
   • Installation (## Installation or ## Quick Start)
   • Documentation (dedicated ## Documentation section OR links within ## Guides/other sections)
   • Supporting Components (## Supporting Components)
   • Contributing (dedicated ## Contributing section OR link within ## Documentation/## Guides)
   • Issue Reporting (dedicated ## Bugs section OR link within ## Contributing/## Documentation)

2. Check heading hierarchy:

   • Title uses #
   • Sections use ##
   • No ### headings (keep it minimal)

3. Count sections - Track which required vs. optional sections are present

4. Validate Content Quality

For each section, validate content:

Title & One-Liner (REQUIRED):

• ✅ Level 1 heading present
• ✅ One-liner present (1-2 sentences)
• ✅ Description is specific, not vague
• ⚠️ If missing or vague: Flag as incomplete

Badges (OPTIONAL, tier-dependent):

• ℹ️ Note if missing for MVP/Production projects
• ✅ If present, check format (shields.io or similar)
• ⚠️ If placeholder badges: Flag as incomplete

Short Description (REQUIRED):

• ✅ ## Description or ## Overview heading present
• ✅ Paragraph length appropriate (3-5 sentences)
• ✅ Business problem context included
• ✅ Solution context included
• ℹ️ Separate ## Business Problem or ## Solution sections acceptable if brief and focused
• ✅ Preferred approach: Integrate business/solution context into single Description/Overview paragraph
• ⚠️ If business context missing: Flag as incomplete

Installation (REQUIRED):

• ✅ ## Installation heading present
• ✅ Installation command in code block
• ✅ Command is actionable (not "install this project")
• ✅ Link to setup guide if docs/setup.md exists
• ⚠️ If missing link to existing setup guide: Flag as incomplete

Documentation (REQUIRED):

• ✅ Documentation links present (can be in dedicated ## Documentation section OR within ## Guides or similar section)
• ✅ At least one documentation link provided
• ✅ Links point to existing files (validate)
• ⚠️ If ADRs exist in adr/ but not linked anywhere: Recommend linking
• ⚠️ If architecture docs exist but not linked anywhere: Recommend linking
• ⚠️ If minimal documentation: Suggest additions

Supporting Components (OPTIONAL):

• ℹ️ Note if missing (not an error)
• ✅ If present, lists actual dependencies with links

Contributing Link (REQUIRED):

• ✅ Contributing guidance or link present (can be dedicated ## Contributing section OR link within ## Documentation/## Guides)
• ✅ Link to CONTRIBUTING.md if file exists (can be in any section)
• ✅ If no CONTRIBUTING.md, basic guidance provided somewhere in README
• ⚠️ If CONTRIBUTING.md exists but not linked anywhere: Recommend linking
• ⚠️ If MVP/Production without CONTRIBUTING.md: Suggest creating one

Issue Reporting (REQUIRED):

• ✅ Issue reporting link or guidance present (can be dedicated ## Bugs section OR link within ## Contributing/## Documentation)
• ✅ Issue tracker link provided somewhere in README
• ⚠️ If no clear path to report issues: Flag as missing

5. Validate Links

Check documentation links referenced in README:

1. Relative links - Verify files exist:

   • docs/setup.md
   • docs/architecture.md
   • adr/
   • CONTRIBUTING.md

2. External links - Note but don't verify (assume valid):

   • GitHub Issues URLs
   • API documentation URLs
   • Confluence links

3. Flag broken links:

   ❌ Broken link: docs/quickstart.md (file not found)
   

6. Check for Undiscovered Documentation

Scan for documentation not linked in README:

# Check for common doc files
test -f docs/architecture.md && echo "Architecture doc exists"
test -d adr && echo "ADRs exist"
test -f CONTRIBUTING.md && echo "Contributing guide exists"

If documentation exists but not linked:

⚠️  Found documentation not linked in README:
   - docs/architecture.md exists but not linked in Documentation section
   - adr/ exists (3 ADRs) but not linked

7. Generate Compliance Report

Tier-appropriate validation using readme-standards skill criteria.

Calculate compliance score:

• Count required content present (out of 6 core requirements: Title, Description/Overview, Installation, Documentation links, Contributing link, Issue reporting)
• Note: Section names can vary - focus on whether essential content/links exist somewhere in README
• Count optional sections present (out of 2: Badges, Supporting Components)
• Count content quality issues (missing business context, broken links, etc.)

Assign compliance level:

• ✅✅✅ Excellent - All required content present, business context clear, comprehensive links, tier-appropriate
• ✅✅ Standard - All required content present, minor content gaps
• ✅ Minimal - Required content mostly present, some significant gaps (missing contributing link or issue reporting)
• ❌ Non-compliant - Missing multiple core requirements

8. Present Results

Console format (--format=console, default):

📋 README Validation Report

Project: {Project Name}
Tier: {Detected Tier}
Compliance Level: ✅✅ Standard

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ COMPLIANT SECTIONS (5/6 required, 1/2 optional)

1. Title & One-Liner - Clear and descriptive
2. Short Description - Business context included
3. Installation - Simple command with setup link
4. Documentation - 3 resources linked
5. Bugs & Enhancements - Issue tracker linked

ℹ️  OPTIONAL SECTIONS

6. Badges - Not present (MVP tier - recommended)
7. Supporting Components - Not applicable

⚠️  INCOMPLETE SECTIONS (1)

8. Contributing - Section present but CONTRIBUTING.md not linked
   → CONTRIBUTING.md exists at ./CONTRIBUTING.md
   → Add link in Contributing section

❌ MISSING SECTIONS (1)

9. (None)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 RECOMMENDATIONS

Priority 1 (Required):
- Link to CONTRIBUTING.md in Contributing section

Priority 2 (Suggested):
- Add badges (project is MVP tier - version, lifecycle, docs, code style)
- Link to ADRs in Documentation section (3 ADRs found in adr/)

Priority 3 (Optional):
- Create quickstart guide (docs/quickstart.md)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ NEXT STEPS

Run `/document-generator:update-readme` to automatically fix issues.

Markdown format (--format=markdown):

Generate detailed report using structure from readme-standards skill Resources section.

Write to output path (default: ./reports/readme-validation-report.md):

# README Validation Report

**Project**: {Project Name}
**Date**: {Date}
**Tier**: {Detected Tier}
**Compliance Level**: ✅✅ Standard

## Summary

- ✅ 5 of 6 required sections compliant
- ⚠️ 1 section incomplete
- ❌ 0 sections missing
- ℹ️ 1 of 2 optional sections present

## Detailed Assessment

### ✅ Compliant Sections

1. **Title & One-Liner** - Clear and descriptive
   - Title: "Customer Segmentation Engine"
   - One-liner present and specific

2. **Short Description** - Business context included
   - Business problem: Marketing teams need customer segmentation
   - Solution: Clustering service for targeted campaigns
   - Core functionality described

...

### ⚠️ Incomplete Sections

8. **Contributing** - Section present but incomplete
   - Section exists with basic guidance
   - CONTRIBUTING.md exists at `./CONTRIBUTING.md` but not linked
   - **Recommendation**: Add link to CONTRIBUTING.md

### ❌ Missing Sections

(None)

## Recommendations

### Priority 1 (Required)
- Link to CONTRIBUTING.md in Contributing section

### Priority 2 (Suggested)
- Add badges (MVP tier: version, lifecycle, docs, code style)
- Link to ADRs in Documentation section

### Priority 3 (Optional)
- Create quickstart guide

## Next Steps

Run `/document-generator:update-readme` to automatically fix issues.

Create reports directory if needed:

mkdir -p reports

Confirm report creation:

✓ Validation report saved to ./reports/readme-validation-report.md

Output Format

Console output - Structured, scannable report with emojis for visual clarity

Markdown report - Detailed, archivable document following structure from readme-standards skill

Validation Levels

Using progressive validation from readme-standards skill:

Level 1: Structure (must pass for minimal compliance):

• All 6 required pieces of content present (title, description/overview, installation, docs links, contributing link, issue reporting)
• Section names can vary - essential content matters more than exact section structure
• Proper heading hierarchy

Level 2: Content (standard compliance):

• Business problem/solution context included (in Description, Overview, or separate sections)
• Actionable installation command
• Valid documentation links
• Contributing guidance accessible (dedicated section or link within docs/guides)
• Issue reporting path clear (dedicated section or link within contributing/docs)

Level 3: Quality (excellent compliance):

• Tier-appropriate badges
• Comprehensive documentation links (architecture, ADRs, guides)
• CONTRIBUTING.md exists and linked for mature projects
• All available documentation linked appropriately

Constraints

• Read-only - This command does not modify README.md
• Link validation - Only check relative links, not external URLs
• Tier-appropriate - Validation criteria adjust based on project tier
• No speculation - Only flag issues based on actual file checks
• Actionable recommendations - Every issue should have clear fix

Error Handling

README.md not found:

• Display clear error message
• Suggest using /document-generator:generate-readme
• Stop execution

Cannot create reports directory:

• Display error with permission issue
• Suggest alternative output path

README.md unreadable:

• Display error (encoding issue, permissions)
• Suggest checking file permissions

Success Criteria

Validation report should:

• ✅ Accurately identify missing/incomplete sections
• ✅ Provide tier-appropriate recommendations
• ✅ Flag broken links and missing doc references
• ✅ Give clear, actionable next steps
• ✅ Assign appropriate compliance level

Related Commands

• /document-generator:generate-readme - Create new README
• /document-generator:update-readme - Fix identified issues