validate-docs-implementation

Validate Documentation vs Implementation

Purpose: Systematically identify and fix mismatches between actual implementation code and documentation.

Load When:

• User says: "validate docs", "check documentation", "docs vs implementation"
• User mentions: "documentation mismatch", "docs don't match code"
• After major code changes that may affect docs
• During pre-release validation

Core Value: Ensures documentation accurately reflects actual implementation, preventing user confusion and wasted debugging time.

---

Quick Reference

What This Skill Does:

1. [OK] Analyzes implementation code (scripts, core logic)
2. [OK] Identifies what the code actually creates/does
3. [OK] Searches all documentation for references to those entities
4. [OK] Compares documented behavior vs actual behavior
5. [OK] Fixes all mismatches systematically
6. [OK] Provides summary of changes made

Typical Mismatches Found:

• File names (e.g., docs say "design.md" but code creates "plan.md")
• Folder structure (e.g., docs missing "02-resources/" directory)
• Counts (e.g., docs say "3 files" but script creates "4 directories + 3 files")
• Naming conventions (e.g., old vs new terminology)
• References to deprecated features

---

Workflow: 5-Step Validation Process

Step 1: Analyze Implementation

Goal: Understand what the code actually does

Actions:

1. Read the implementation file(s) identified by user
2. Document exactly what it creates/generates/does:
   • Files created (names, locations, count)
   • Folders created (names, structure, count)
   • Data structures used
   • Behavior patterns
3. Create a reference list of "ground truth" facts

Example Output:

## Implementation Analysis: init_build.py

**Creates**:
- 4 directories: 01-planning/, 02-resources/, 03-working/, 04-outputs/
- 3 files in 01-planning/: overview.md, plan.md, steps.md

**Does NOT create**:
- design.md (old name)
- tasks.md (old name)
- requirements.md (never existed)