# Code Docs Quality

> Analyze docs quality across PRDs, ADRs, PRPs, CLAUDE.md, .claude/rules/.

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.

- Page: https://ss33.ai/skills/laurigates/code-docs-quality-79672125360
- Publisher: laurigates
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Developer docs & tooling](https://ss33.ai/skills/category/software-development-t44z8z/developer-docs-and-tooling-nich6w)
- License: MIT
- Source: https://github.com/laurigates/claude-plugins/blob/f8dc5cd452a2ed3af86ab7e65949e0653e88127f/code-quality-plugin/skills/code-docs-quality/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/laurigates/code-docs-quality-79672125360

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

**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](references/doc-standards.md#42-adr-structure-validation).

### 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](references/doc-standards.md#52-prd-structure-validation).

### 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](references/doc-standards.md#62-prp-structure-validation).

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

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](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](references/report-templates.md#91-executive-summary).

### 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](references/doc-standards.md#for-documentation-standards).

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