code-docs-quality

Analyze and validate documentation quality for a codebase, ensuring PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ are up to standards and current.

When to Use This Skill

Context

• Target path: $1 (defaults to current directory if not specified)
• Blueprint dir exists: !find . -path '*/.claude/blueprints' -maxdepth 2 -type d
• CLAUDE.md exists: !find . -maxdepth 1 -name 'CLAUDE.md' -type f
• Rules directory: !find . -path '*/.claude/rules/*' -maxdepth 3 -name '*.md'
• ADRs (docs/adr): !find . -path '*/docs/adr/*' -maxdepth 3 -name '*.md'
• ADRs (docs/adrs): !find . -path '*/docs/adrs/*' -maxdepth 3 -name '*.md'
• PRDs (docs/prds): !find . -path '*/docs/prds/*' -maxdepth 3 -name '*.md'
• PRDs (blueprints): !find . -path '*/.claude/blueprints/prds/*' -maxdepth 4 -name '*.md'
• PRPs (docs/prps): !find . -path '*/docs/prps/*' -maxdepth 3 -name '*.md'
• PRPs (blueprints): !find . -path '*/.claude/blueprints/prps/*' -maxdepth 4 -name '*.md'

Parameters

• $1: Path to analyze (defaults to current directory)

Your Task

Perform a comprehensive documentation quality analysis using the following methodology:

Phase 1: Plan the analysis

Track the analysis against this checklist (via TodoWrite when the session has the task tools — see .claude/rules/agentic-permissions.md § Task-tool availability — otherwise carry it as a checklist in your response):

- 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

Phase 2: CLAUDE.md Analysis

2.1 Check Existence and Structure

• Verify CLAUDE.md exists at project root
• Check for required YAML frontmatter:

  ---
  created: YYYY-MM-DD
  modified: YYYY-MM-DD
  reviewed: YYYY-MM-DD
  ---
  

2.2 Content Quality Checks

• Completeness: Does it provide clear project context?

  • Project structure overview
  • Development conventions
  • Key rules and guidelines
  • Plugin/tool references if applicable

• Clarity: Is it well-organized and readable?

  • Clear sections with headers
  • Proper markdown formatting
  • Tables for structured data
  • Examples where helpful

• Accuracy: Check for outdated information

  • Compare modified date with recent git commits
  • Look for references to deprecated patterns
  • Validate file paths and references exist

2.3 Best Practices

Check against CLAUDE.md standards:

• Should guide AI assistants on how to work with the codebase
• Include project structure explanation
• Reference key rules and conventions
• Point to additional documentation (ADRs, rules)
• Use tables for quick reference
• Keep focused and concise

Phase 3: .claude/rules/ Analysis

3.1 Directory Structure

• Verify .claude/rules/ directory exists
• List all rule files present
• Check for recommended core rules:
  • Architecture/design patterns
  • Coding standards
  • Development workflows
  • Testing requirements

3.2 Individual Rule Validation

For each rule file in .claude/rules/:

Required Frontmatter:

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
name: docs-quality-check
---

Content Standards:

• Clear title and purpose
• Well-defined scope
• Specific, actionable guidance
• Examples where appropriate
• Related rules cross-referenced

3.3 Rules Organization

• Are rules properly categorized?
• Are there too many/too few rules?
• Is there duplication or conflict between rules?
• Are rule names descriptive and consistent?

Phase 4: ADR Validation

4.1 Check ADR Directory

• Verify docs/adrs/ or docs/adr/ exists
• Check for ADR index/README
• List all ADR files (should be numbered: 0001-title.md)

4.2 ADR Structure Validation

For each ADR, verify:

Naming Convention:

• Format: NNNN-kebab-case-title.md (e.g., 0001-plugin-architecture.md)
• Sequential numbering
• Descriptive titles

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]

4.3 ADR Quality Checks

• Status accuracy: Are deprecated ADRs marked?
• Completeness: Do ADRs have all required sections?
• Relevance: Are ADRs still applicable to current codebase?
• Index maintenance: Is the ADR index up to date?

4.4 Coverage Analysis

• Do ADRs cover major architectural decisions?
• Are recent significant changes documented?
• Are there obvious undocumented decisions?

Phase 5: PRD Validation

5.1 Check PRD Directory

• Verify docs/prds/ or .claude/blueprints/prds/ exists
• List all PRD files

5.2 PRD Structure Validation

For 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
name: docs-quality-check
---

Required Sections:

• Executive Summary / Problem Statement
• Stakeholders & User Personas
• Functional Requirements
• Non-Functional Requirements
• Success Metrics
• Scope (In/Out of scope)
• Technical Considerations

5.3 PRD Quality Checks

• Clarity: Are requirements specific and measurable?
• Completeness: Are all key sections present?
• Status: Is the status field accurate?
• Traceability: Can requirements be traced to implementations?
• User focus: Are user needs clearly articulated?

Phase 6: PRP Validation

6.1 Check PRP Directory

• Verify docs/prps/ exists (Blueprint methodology)
• List all PRP files

6.2 PRP Structure Validation

For each PRP, verify:

Required Sections:

• Goal & Why
• Success Criteria (testable)
• Context (documentation refs, codebase intelligence, known gotchas)
• Implementation Blueprint (architecture, task breakdown)
• TDD Requirements (test strategy, critical test cases)
• Validation Gates (executable commands)
• Confidence Score (0-10 across dimensions)

6.3 PRP Quality Checks

• Specificity: Are file paths and code references explicit?
• Testability: Are success criteria measurable?
• Completeness: Does the confidence score match content quality?
• Actionability: Can this PRP be executed immediately?
• Context: Is there enough curated context for implementation?

Phase 7: Freshness Analysis

7.1 Check Last Modified Dates

For all documentation:

• Compare modified frontmatter dates with git history
• Identify stale documents (>6 months without review)
• Flag documents that should be reviewed based on related code changes

Use 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"

7.2 Cross-Reference with Code Changes

• Have there been major code changes without doc updates?
• Are ADRs current with actual architecture?
• Do PRDs reflect implemented features accurately?

Phase 8: Generate Quality Report

8.1 Documentation Inventory

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] |

8.2 Quality Score

Calculate an overall quality score:

Rating Guide:

• 9-10: Excellent - Well-maintained, comprehensive
• 7-8: Good - Minor improvements needed
• 5-6: Fair - Several issues to address
• 3-4: Poor - Major gaps or outdated
• 0-2: Critical - Missing or severely lacking

8.3 Issues and Recommendations

Categorize findings:

Critical Issues (must fix):

• Missing required documentation
• Severe structural problems
• Completely outdated information

Warnings (should fix):

• Stale documentation (>6 months)
• Missing frontmatter
• Incomplete sections
• Minor structural issues

Suggestions (nice to have):

• Additional documentation that would help
• Improved organization
• Better cross-referencing
• Enhanced examples

8.4 Actionable Recommendations

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 `/code:docs-quality` monthly
- Update `modified` dates when editing docs
- Review `reviewed` dates quarterly
- Use `/blueprint:adr` for new architecture decisions
- Use `/blueprint:prd` for new features

Phase 9: Present Results

9.1 Executive Summary

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.

9.2 Full Report

Present the complete analysis with:

• Documentation inventory
• Quality scores by category
• Detailed findings
• Actionable recommendations
• Maintenance checklist

9.3 Guidance for Improvement

Help the user understand next steps:

• If Blueprint not initialized → suggest /blueprint:init
• If ADRs missing → suggest /blueprint:adr
• If PRDs missing → suggest /blueprint:prd
• If documentation tooling not configured → suggest /configure:docs
• If documentation outdated → provide update checklist
• If standards not followed → show examples and templates

Best Practices

For the Analysis

• Be thorough but concise
• Focus on actionable issues
• Provide specific file/line references
• Include examples of good vs bad patterns
• Suggest concrete fixes, not just problems

For Documentation Standards

• Frontmatter: Always include created/modified/reviewed dates
• Structure: Follow established templates (ADR, PRD, PRP)
• Clarity: Write for future maintainers and AI assistants
• Maintenance: Review quarterly, update modified dates
• Cross-reference: Link related documentation
• Examples: Include code snippets and real examples
• Scope: Keep focused - one concern per document

Error Handling

• If not a git repository → skip git-based freshness checks
• If directories don't exist → note in report as missing
• If files malformed → flag specific parsing errors
• If unable to read file → note permission/access issues
• If Blueprint not initialized → suggest initialization before creating docs

Output Format

Use clear markdown formatting:

• Tables for structured data
• Checkboxes for action items
• Code blocks for examples
• Emoji indicators (✅ ❌ ⚠️) for quick scanning
• Collapsible sections for detailed analysis (if supported)

Remember: The goal is to help users maintain high-quality, current documentation that serves both human developers and AI assistants effectively.