Initial commit
This commit is contained in:
Zhongwei Li
386
commands/validate-readme.md
Normal file
386
commands/validate-readme.md
Normal file
@@ -0,0 +1,386 @@
|
||||
---
|
||||
description: Audit existing README.md compliance with standards without making changes
|
||||
---
|
||||
|
||||
# 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:**
|
||||
```bash
|
||||
/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**:
|
||||
|
||||
```bash
|
||||
# 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`):
|
||||
|
||||
```markdown
|
||||
# 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**:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user