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

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 and the required MADR sections against references/doc-standards.md.

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 and required sections against references/doc-standards.md.

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 the required sections against references/doc-standards.md.

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

Build the report in four parts — 8.1 documentation inventory table, 8.2 quality score (0-10 per category, with rating guide), 8.3 issues categorized as Critical / Warnings / Suggestions, 8.4 actionable recommendations — using the templates in references/report-templates.md.

Phase 9: Present Results

9.1 Executive Summary

Show a clear, concise summary using the executive-summary template in references/report-templates.md.

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:derive-plans
• If PRDs missing → suggest /blueprint:derive-plans
• 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

The general standards to recommend (frontmatter dates, templates, maintenance cadence) are in references/doc-standards.md.

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.