Code Docs Quality

---
created: 2026-01-08
modified: 2026-09-02
reviewed: 2026-09-02
description: "Analyze docs quality across PRDs, ADRs, PRPs, CLAUDE.md, .claude/rules/. Use when auditing documentation, checking for stale ADRs/PRDs, or validating rule frontmatter structure."
allowed-tools: Read, Glob, Grep, Bash(markdownlint *), Bash(vale *), Task
args: "[PATH]"
argument-hint: "[PATH]"
name: 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

| Use this skill when... | Use something else instead when... |
|------------------------|------------------------------------|
| Auditing PRD/ADR/PRP/CLAUDE.md/rules for staleness, frontmatter, structure | Reviewing source code quality and architecture → `code-review` |
| Scoring whether CLAUDE.md still matches recent code changes | Detecting unused/dead code in source → `code-dead-code` |
| Validating `.claude/rules/` markdown structure and metadata | Refactoring source modules → `code-refactor` |
| Cataloging missing or orphaned ADRs / PRDs | Auditing dependencies and licensing → `code-dep-audit` |

## 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:
  ```yaml
  ---
  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**:
```yaml
---
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):
```markdown
# 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):
```yaml
---
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:
```bash
# 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:

```markdown
## 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:

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

```markdown
## 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.