documentation-quality-analysis

laurigates 的头像作者 laurigates

Analyze and validate documentation quality for PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ to ensure standards compliance and freshness

📖 中文导读:Analyze and validate documentation quality for PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ to ensure standards compliance and freshness 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Documentation Quality Analysis description: Analyze and validate documentation quality for PRDs, ADRs, PRPs, CLAUDE.md, and .claude/rules/ to ensure standards compliance and freshness allowed-tools: Bash, Read, Grep, Glob, TodoWrite created: 2026-01-08 modified: 2026-01-08 reviewed: 2026-01-08

Documentation Quality Analysis

Expert analysis of technical documentation quality, structure, and maintenance for codebases using Blueprint Development methodology and Claude Code conventions.

Core Expertise

Documentation quality is critical for:

  • AI Assistant Context: Well-structured docs enable better AI assistance
  • Knowledge Preservation: Captures architectural decisions and rationale
  • Onboarding: Accelerates new team member productivity
  • Maintenance: Prevents knowledge loss and technical debt

This skill provides systematic analysis of:

  • CLAUDE.md: Project-level AI assistant instructions
  • .claude/rules/: Modular rule definitions
  • ADRs: Architecture Decision Records
  • PRDs: Product Requirements Documents
  • PRPs: Product Requirement Prompts (Blueprint methodology)

Documentation Types & Standards

CLAUDE.md

Purpose: Guide AI assistants on working with the codebase

Required Elements:

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

# Project Name

## Project Structure
[Directory layout and organization]

## Rules
[Key rules and conventions]

## Development Workflow
[Common tasks and patterns]

## Conventions
[Naming, structure, etc.]

Quality Indicators:

  • ✅ Clear project structure overview
  • ✅ References to .claude/rules/ files
  • ✅ Tables for quick reference
  • ✅ Focused and concise (not a full manual)
  • ✅ Updated within last 6 months

.claude/rules/

Purpose: Modular, reusable rule definitions

File Structure:

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

# Rule Title

[Clear, specific guidance on a single concern]

Quality Indicators:

  • ✅ One concern per rule file
  • ✅ Descriptive file names (kebab-case)
  • ✅ Clear scope and applicability
  • ✅ Actionable guidance with examples
  • ✅ Cross-references to related rules

Common Rules:

  • plugin-structure.md - Plugin organization
  • release-please.md - Version management
  • skill-development.md - Skill creation patterns
  • agentic-optimization.md - CLI optimization for AI
  • command-naming.md - Command conventions

Architecture Decision Records (ADRs)

Purpose: Document significant architectural choices

Format: MADR (Markdown Architecture Decision Records)

Structure:

# ADR-NNNN: Title

**Date**: YYYY-MM
**Status**: Accepted | Superseded | Deprecated
**Deciders**: [who decided]

## Context
[Problem and constraints]

## Decision
[What was decided]

## Consequences
[Positive and negative outcomes]

Location: docs/adrs/ or docs/adr/

Naming: Sequential numbers, kebab-case titles

  • 0001-plugin-based-architecture.md
  • 0002-domain-driven-organization.md

Quality Indicators:

  • ✅ All major architectural decisions documented
  • ✅ Sequential numbering without gaps
  • ✅ Clear context and rationale
  • ✅ Consequences documented (both pros and cons)
  • ✅ Index file maintained
  • ✅ Status accurate (Accepted/Superseded/Deprecated)

Product Requirements Documents (PRDs)

Purpose: Define what needs to be built and why

Location: docs/prds/ or .claude/blueprints/prds/

Structure:

# Project/Feature Name - PRD

**Created**: YYYY-MM-DD
**Status**: Draft | Active | Implemented | Archived
**Version**: X.Y

## Executive Summary
- Problem Statement
- Proposed Solution
- Business Impact

## Stakeholders & Personas
[Who cares and who uses]

## Functional Requirements
[What the system must do]

## Non-Functional Requirements
[Performance, security, accessibility]

## Success Metrics
[How we measure success]

## Scope
- In Scope
- Out of Scope

## Technical Considerations
[Architecture, dependencies, integrations]

Quality Indicators:

  • ✅ Clear problem statement
  • ✅ User personas defined
  • ✅ Specific, measurable requirements
  • ✅ Success metrics defined
  • ✅ Scope explicitly bounded
  • ✅ Status field accurate
  • ✅ Updated when requirements change

Product Requirement Prompts (PRPs)

Purpose: AI-executable feature specifications (Blueprint methodology)

Location: docs/prps/

Structure:

# [Feature Name] PRP

## Goal & Why
[One sentence goal + business justification]

## Success Criteria
[Specific, testable acceptance criteria]

## Context
- **Documentation References**: [URLs with sections]
- **ai_docs References**: [Curated context]
- **Codebase Intelligence**: [Files, patterns, snippets]
- **Known Gotchas**: [Warnings and mitigations]

## Implementation Blueprint
[Architecture decision + task breakdown + pseudocode]

## TDD Requirements
[Test strategy + critical test cases]

## Validation Gates
[Executable commands for quality gates]

## Confidence Score: X/10
- Context Completeness: X/10
- Implementation Clarity: X/10
- Gotchas Documented: X/10
- Validation Coverage: X/10

Quality Indicators:

  • ✅ Explicit file paths and line numbers
  • ✅ Code snippets from actual codebase
  • ✅ Executable validation commands
  • ✅ Honest confidence scoring (≥7 for execution)
  • ✅ Known gotchas with mitigations
  • ✅ Test strategy defined

Quality Analysis Commands

Check for Frontmatter

# Check if file has required frontmatter
grep -A 5 "^---$" CLAUDE.md | grep -E "(created|modified|reviewed):"

# Find files missing frontmatter
for f in docs/adrs/*.md; do
  grep -q "^---$" "$f" || echo "Missing frontmatter: $f"
done

Validate ADR Naming

# Check ADR naming convention (NNNN-title.md)
find docs/adrs -name "*.md" ! -name "README.md" ! -name "[0-9][0-9][0-9][0-9]-*.md"

# Check for sequential numbering
ls docs/adrs/[0-9]*.md | sort

Check Documentation Freshness

# Find docs not modified in 6 months
find docs -name "*.md" -mtime +180

# Check git history for documentation
git log --since="6 months ago" --oneline -- docs/ .claude/ CLAUDE.md

# Last modification of specific doc
git log -1 --format="%ai %s" -- CLAUDE.md

Validate Sections

# Check if ADR has required sections
grep -E "^## (Context|Decision|Consequences)" docs/adrs/0001-*.md

# Check PRD completeness
grep -E "^## (Executive Summary|Functional Requirements|Success Metrics)" docs/prds/*.md

Count Documentation

# Documentation inventory
echo "CLAUDE.md: $(test -f CLAUDE.md && echo '✅' || echo '❌')"
echo "Rules: $(ls .claude/rules/*.md 2>/dev/null | wc -l) files"
echo "ADRs: $(ls docs/adrs/*.md 2>/dev/null | grep -v README | wc -l) files"
echo "PRDs: $(ls docs/prds/*.md 2>/dev/null | wc -l) files"
echo "PRPs: $(ls docs/prps/*.md 2>/dev/null | wc -l) files"

Quality Scoring Methodology

Overall Quality Score (0-10)

Calculate as average of five dimensions:

Dimension Score 9-10 Score 7-8 Score 5-6 Score 3-4 Score 0-2
Structure Perfect org, all conventions Minor naming issues Some disorganization Poor structure Missing/chaotic
Completeness All sections present 1-2 missing sections Several gaps Major gaps Severely incomplete
Freshness Updated <3mo Updated <6mo Updated <12mo Stale >12mo Abandoned >24mo
Standards Perfect compliance Minor deviations Some non-compliance Poor compliance No standards
Content Quality Excellent clarity Good with minor issues Acceptable Unclear/vague Unusable

Dimension-Specific Scoring

Structure (Organization & Naming):

  • File naming conventions followed
  • Directory structure logical
  • Sequential numbering (ADRs)
  • Proper categorization (.claude/rules/)

Completeness (Required Elements):

  • All required sections present
  • Frontmatter complete
  • Cross-references included
  • Examples provided where needed

Freshness (Currency):

  • modified dates recent
  • Git commits align with modified dates
  • Reflects current codebase state
  • Regular review cadence

Standards Compliance (Format Adherence):

  • Frontmatter present and correct
  • Template structure followed
  • Markdown formatting valid
  • Links and references work

Content Quality (Clarity & Usefulness):

  • Clear, specific language
  • Actionable guidance
  • Relevant examples
  • Appropriate detail level
  • No contradictions or confusion

Common Documentation Issues

Critical Issues (Must Fix)

Issue Detection Fix
Missing CLAUDE.md ! -f CLAUDE.md Create using project template
No frontmatter ! grep "^---$" Add YAML frontmatter with dates
Completely outdated modified >24mo Review and update or archive
Broken structure Missing required sections Follow template structure
Invalid ADR naming Not NNNN-title.md Rename to follow convention

Warnings (Should Fix)

Issue Detection Fix
Stale docs modified >6mo Review and update modified date
Missing sections Template mismatch Add missing sections
No ADR index No README in adrs/ Create index file
Vague requirements Review content Add specificity and examples
Low confidence PRP Score <7 Research more context

Suggestions (Nice to Have)

Issue Detection Fix
Sparse rules <3 rule files Extract common patterns to rules
No PRPs Empty prps/ dir Create PRPs for planned features
Missing examples Grep for code blocks Add code examples
Poor cross-refs Few markdown links Link related documentation
No metrics PRD without success criteria Define measurable metrics

Analysis Workflow

1. Inventory Phase

Collect all documentation:

# List all documentation
find . -name "CLAUDE.md" -o -path "*/.claude/rules/*.md" -o -path "*/docs/adrs/*.md" -o -path "*/docs/prds/*.md" -o -path "*/docs/prps/*.md"

Create inventory:

  • Count files by type
  • Note missing standard docs
  • Check directory structure

2. Validation Phase

For each document type:

  • Read the file
  • Check frontmatter exists and is valid
  • Verify required sections present
  • Validate naming conventions
  • Assess content quality

3. Freshness Phase

Check currency:

# Git last modified
git log -1 --format="%ai" -- path/to/doc.md

# Compare frontmatter vs git
# (modified date should match recent git activity)

Flag stale documents:

  • 6mo: Warning

  • 12mo: Concern

  • 24mo: Critical

4. Scoring Phase

Calculate scores:

  1. Structure: File org, naming (0-10)
  2. Completeness: Sections present (0-10)
  3. Freshness: Currency (0-10)
  4. Standards: Format compliance (0-10)
  5. Content: Quality, clarity (0-10)

Overall = Average of 5 dimensions

5. Reporting Phase

Generate report:

  • Executive summary with overall score
  • Inventory table
  • Dimension scores
  • Critical issues (must fix)
  • Warnings (should fix)
  • Suggestions (nice to have)
  • Actionable recommendations with specific files/fixes

Agentic Optimizations

Task Optimized Approach
List docs find with multiple -name patterns, single command
Check frontmatter grep -l "^---$" *.md batch check
Validate names Shell globbing [0-9][0-9][0-9][0-9]-*.md
Count files Pipeline `ls
Git history git log --since="6 months ago" --oneline
Batch validation for loop over files, collect issues

Quick Reference

Frontmatter Template

---
created: 2026-01-08
modified: 2026-01-08
reviewed: 2026-01-08
---

ADR Quick Template

# ADR-NNNN: Title

**Date**: 2026-01
**Status**: Accepted

## Context
[Why this decision?]

## Decision
[What did we decide?]

## Consequences
✅ Pros: ...
❌ Cons: ...

Quality Score Guide

  • 9-10: Excellent - Reference quality
  • 7-8: Good - Minor improvements
  • 5-6: Fair - Several issues
  • 3-4: Poor - Major work needed
  • 0-2: Critical - Severe problems
  • /docs:quality-check - Run comprehensive analysis
  • /blueprint:init - Initialize Blueprint Development
  • /blueprint:prd - Generate PRD from project docs
  • /blueprint:adr - Generate ADRs from codebase
  • /blueprint:prp-create - Create PRP for feature

Best Practices

  1. Regular Reviews: Run quality checks monthly
  2. Update Modified Dates: When editing, update frontmatter
  3. Quarterly Reviews: Update reviewed date every 3 months
  4. Template Adherence: Use standard templates consistently
  5. Specificity: Prefer explicit over vague (file paths, metrics)
  6. Cross-Reference: Link related documentation
  7. Examples: Include code snippets and real examples
  8. Scope Management: One concern per document
  9. Git Sync: Commit docs with code changes
  10. AI-Friendly: Write for both humans and AI assistants

Error Handling

# Safe directory checks
test -d docs/adrs && ls docs/adrs || echo "ADRs directory not found"

# Safe file reads with fallback
cat CLAUDE.md 2>/dev/null || echo "CLAUDE.md not found"

# Git-aware freshness (works without git)
git log -1 --format="%ai" -- CLAUDE.md 2>/dev/null || echo "No git history"

# Glob with no-match handling
shopt -s nullglob
for f in docs/adrs/*.md; do
  echo "Processing $f"
done

References

  • MADR (Markdown ADR) - ADR template format
  • Michael Nygard ADR - Original ADR format
  • Blueprint Development methodology - PRP/PRD patterns
  • .claude/rules/ - Project-specific documentation standards