Analyze codebase documentation quality - PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/
Analyzes documentation quality across PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ to identify gaps and provide improvement recommendations.
/plugin marketplace add laurigates/claude-plugins/plugin install code-quality-plugin@lgates-claude-plugins[PATH]docs/Analyze and validate documentation quality for a codebase, ensuring PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ are up to standards and current.
echo "${1:-.}"test -d ${1:-.}/.claude/blueprints && echo "✅ Yes" || echo "❌ No"test -f ${1:-.}/CLAUDE.md && echo "✅ Yes" || echo "❌ No"test -d ${1:-.}/.claude/rules && echo "✅ Yes ($(ls ${1:-.}/.claude/rules/*.md 2>/dev/null | wc -l) files)" || echo "❌ No"(test -d ${1:-.}/docs/adr && echo "✅ Yes ($(ls ${1:-.}/docs/adr/*.md 2>/dev/null | wc -l) files)") || (test -d ${1:-.}/docs/adrs && echo "✅ Yes ($(ls ${1:-.}/docs/adrs/*.md 2>/dev/null | wc -l) files)") || echo "❌ No"(test -d ${1:-.}/docs/prds && echo "✅ Yes ($(ls ${1:-.}/docs/prds/*.md 2>/dev/null | wc -l) files)") || (test -d ${1:-.}/.claude/blueprints/prds && echo "✅ Yes ($(ls ${1:-.}/.claude/blueprints/prds/*.md 2>/dev/null | wc -l) files)") || echo "❌ No"(test -d ${1:-.}/docs/prps && echo "✅ Yes ($(ls ${1:-.}/docs/prps/*.md 2>/dev/null | wc -l) files)") || (test -d ${1:-.}/.claude/blueprints/prps && echo "✅ Yes ($(ls ${1:-.}/.claude/blueprints/prps/*.md 2>/dev/null | wc -l) files)") || echo "❌ No"$1: Path to analyze (defaults to current directory)Perform a comprehensive documentation quality analysis using the following methodology:
Create a structured todo list for tracking the analysis:
- Analyze CLAUDE.md structure and quality
- Check .claude/rules/ directory and standards
- Validate ADRs (Architecture Decision Records)
- Validate PRDs (Product Requirements Documents)
- Validate PRPs (Product Requirement Prompts)
- Check documentation freshness and git history
- Generate quality report with recommendations
CLAUDE.md exists at project root---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---
Completeness: Does it provide clear project context?
Clarity: Is it well-organized and readable?
Accuracy: Check for outdated information
Check against CLAUDE.md standards:
.claude/rules/ directory existsFor each rule file in .claude/rules/:
Required Frontmatter:
---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---
Content Standards:
docs/adrs/ or docs/adr/ existsFor each ADR, verify:
Naming Convention:
NNNN-kebab-case-title.md (e.g., 0001-plugin-architecture.md)Required Sections (MADR format):
# ADR-NNNN: Title
**Date**: YYYY-MM
**Status**: Accepted | Superseded | Deprecated
**Deciders**: [who made the decision]
## Context
[The issue motivating this decision]
## Decision
[The change being proposed or made]
## Consequences
[What becomes easier or harder]
docs/prds/ or .claude/blueprints/prds/ existsFor each PRD, verify:
Frontmatter (if using Blueprint methodology):
---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
status: Draft | Active | Implemented | Archived
---
Required Sections:
docs/prps/ exists (Blueprint methodology)For each PRP, verify:
Required Sections:
For all documentation:
modified frontmatter dates with git historyUse git to check activity:
# Check recent commits affecting docs
git log --since="6 months ago" --oneline -- docs/ .claude/ CLAUDE.md 2>/dev/null || echo "Not a git repo or no history"
# Check when documentation was last touched
git log -1 --format="%ai %s" -- CLAUDE.md 2>/dev/null || echo "No git history"
Generate a summary table:
## Documentation Inventory
| Document Type | Status | Count | Issues |
|---------------|--------|-------|--------|
| CLAUDE.md | ✅/❌ | 1 | [list issues] |
| .claude/rules/ | ✅/❌ | N files | [list issues] |
| ADRs | ✅/❌ | N files | [list issues] |
| PRDs | ✅/❌ | N files | [list issues] |
| PRPs | ✅/❌ | N files | [list issues] |
Calculate an overall quality score:
| Category | Score (0-10) | Notes |
|---|---|---|
| Structure | X | File organization, naming |
| Completeness | X | Required sections present |
| Freshness | X | Recent updates, git sync |
| Standards Compliance | X | Frontmatter, format |
| Content Quality | X | Clarity, specificity |
| Overall | X | Average score |
Rating Guide:
Categorize findings:
Critical Issues (must fix):
Warnings (should fix):
Suggestions (nice to have):
For each issue, provide specific guidance:
## Recommendations
### Immediate Actions
1. [ ] Fix [specific issue] in [file]
- **Why**: [reason]
- **How**: [specific steps]
- **Command**: [if applicable]
2. [ ] Update [document]
- **Why**: [reason]
- **How**: [specific steps]
### Maintenance Tasks
1. [ ] Review and update stale documents:
- [file1] - last modified [date]
- [file2] - last modified [date]
2. [ ] Improve documentation coverage:
- [ ] Document [undocumented decision]
- [ ] Create ADR for [architectural choice]
### Best Practices
- Run `/docs:quality-check` monthly
- Update `modified` dates when editing docs
- Review `reviewed` dates quarterly
- Use `/blueprint:adr` for new architecture decisions
- Use `/blueprint:prd` for new features
Show a clear, concise summary:
📊 Documentation Quality Report
═══════════════════════════════
Overall Score: X/10 ([Excellent/Good/Fair/Poor/Critical])
✅ Strengths:
- [strength 1]
- [strength 2]
⚠️ Issues Found:
- [issue 1]
- [issue 2]
📋 Recommendations:
- [top recommendation 1]
- [top recommendation 2]
See full report below for details.
Present the complete analysis with:
Help the user understand next steps:
/blueprint:init/blueprint:adr/blueprint:prdUse clear markdown formatting:
Remember: The goal is to help users maintain high-quality, current documentation that serves both human developers and AI assistants effectively.