code-docs-quality

What this skill does

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 .claude -maxdepth 1 -name 'blueprints' -type d`
- CLAUDE.md exists: !`find . -maxdepth 1 -name 'CLAUDE.md' -type f`
- Rules directory: !`find .claude/rules -maxdepth 1 -name '*.md'`
- ADRs (docs/adr): !`find docs/adr -maxdepth 1 -name '*.md'`
- ADRs (docs/adrs): !`find docs/adrs -maxdepth 1 -name '*.md'`
- PRDs (docs/prds): !`find docs/prds -maxdepth 1 -name '*.md'`
- PRDs (blueprints): !`find .claude/blueprints/prds -maxdepth 1 -name '*.md'`
- PRPs (docs/prps): !`find docs/prps -maxdepth 1 -name '*.md'`
- PRPs (blueprints): !`find .claude/blueprints/prps -maxdepth 1 -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: Create Todo List

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

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