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