Skip to content

DOCUMENTATION-AUDIT.md

Latest commit

 

History

History
447 lines (352 loc) · 14.3 KB

DOCUMENTATION-AUDIT.md

File metadata and controls

447 lines (352 loc) · 14.3 KB

Documentation Organization Audit & Recommendations

Date: 2026-01-23 Project: Claude Code WordPress Template Purpose: Reorganize documentation to eliminate redundancy and improve clarity

Executive Summary

Current State:

  • 65+ documentation files across 8 directories
  • Significant redundancy (Figma-to-FSE documented in 14 files)
  • Unclear documentation hierarchy
  • Mixing of template docs, internal dev docs, and historical reports
  • Root directory cluttered with 5 markdown files

Recommendations:

  1. Consolidate Figma-to-FSE documentation (14 files → 3-4 files)
  2. Establish clear documentation hierarchy
  3. Archive historical reports and plans
  4. Fix .gitignore to properly track/ignore files
  5. Create single entry point for template users

Critical Issues

Issue 1: Figma-to-FSE Documentation Sprawl

Problem: Same information documented in 14+ files

Current Structure:

Root Level:
├── FIGMA-TO-FSE-AUTOMATION.md          # Pattern-first overview
└── IMPLEMENTATION-SUMMARY.md           # Improvement status

.claude/skills/figma-to-fse-autonomous-workflow/:
├── SKILL.md                            # Main skill (22KB)
├── README.md                           # Skill overview
├── IMPLEMENTATION-GUIDE.md             # Setup instructions
├── TESTING-GUIDE.md                    # Validation procedures
├── AUTONOMOUS-EXECUTION.md             # Workflow details
└── TEMPLATE-EXAMPLES.md                # Examples

.claude/skills/fse-pattern-first-architecture/:
└── skill.md                            # Pattern-first approach

.claude/agents/:
├── figma-fse-converter.md              # Agent definition
└── (PATTERN-FIRST-ARCHITECTURE.md moved to docs/architecture/)

.claude/reports/:
├── figma-fse-implementation-plan.md    # Phase breakdown
├── figma-fse-comparison.md             # Comparison analysis
└── rcvmd-conversion-report.md          # Conversion results

.claude/plans/:
└── figma-fse-rcvmd-conversion.md       # Conversion plan

Redundancy Analysis:

  • Pattern-first architecture: Documented 4 times
  • Setup/implementation: Documented 3 times
  • Testing/validation: Documented 2 times
  • Examples: Spread across multiple files

Recommendation: Consolidate to 3 files

docs/figma-to-wordpress/:
├── README.md                    # User guide + quick start
├── IMPLEMENTATION.md            # Technical implementation details
└── EXAMPLES.md                  # Template examples

archive/figma-development/:      # Historical docs
├── implementation-plan.md       # Original planning
├── comparison.md                # Analysis from development
└── rcvmd-conversion.md          # March Medical case study

Issue 2: Plugin/Agent/Skill Documentation Duplication

Problem: Same information in 3-4 different files

Plugin Documentation (3 locations):

  1. CLAUDE.md - Lists 5 plugins + descriptions
  2. .claude/SETUP-COMPLETE.md - Setup verification
  3. .claude/PLUGINS-REFERENCE.md - Command reference

Recommendation:

  • Keep .claude/PLUGINS-REFERENCE.md as single source of truth
  • CLAUDE.md should reference it, not duplicate
  • Move SETUP-COMPLETE.md to archive/setup/

Agent Documentation (2 locations + 27 files):

  1. CLAUDE.md - Lists 24 agents
  2. .claude/CUSTOM-AGENTS-GUIDE.md - Same 24 agents
  3. .claude/agents/*.md - Individual definitions (27 files)

Recommendation:

  • Keep .claude/CUSTOM-AGENTS-GUIDE.md as catalog
  • Keep individual agent files (functional requirement)
  • Remove agent list from CLAUDE.md, just reference guide

Skill Documentation (2 locations + 10 files):

  1. CLAUDE.md - Lists 8 WordPress skills
  2. .claude/skills/README.md - Same 8 skills
  3. Individual SKILL.md files in subdirectories

Recommendation:

  • Keep .claude/skills/README.md as catalog
  • Keep individual skill files (functional requirement)
  • Remove skill list from CLAUDE.md, just reference catalog

Issue 3: Root Directory Clutter

Current Root-Level Markdown Files:

├── README.md                      # Project overview
├── CLAUDE.md                      # Claude Code guidance (400+ lines)
├── FIGMA-TO-FSE-AUTOMATION.md     # Figma automation overview
├── IMPLEMENTATION-SUMMARY.md      # Status document
└── LOCAL-DEVELOPMENT.md           # Docker setup

Problem: Unclear hierarchy, too many entry points

Recommendation: Streamline to 2 entry points

Root:
├── README.md                      # Main entry point for template users
└── CLAUDE.md                      # Claude Code automation reference

docs/:
├── LOCAL-DEVELOPMENT.md           # Docker setup guide
└── figma-to-wordpress/            # Figma conversion docs
    ├── README.md
    ├── IMPLEMENTATION.md
    └── EXAMPLES.md

archive/:
└── development/
    ├── IMPLEMENTATION-SUMMARY.md  # Historical status
    └── figma-development/         # Historical reports

Issue 4: Unclear Documentation Hierarchy

Problem: No clear path for different user types

Current: User doesn't know where to start Needed: Clear entry points for:

  1. Template users (want to use template)
  2. Developers (want to modify template)
  3. Claude Code automation (how to use automation features)

Recommendation: Create clear hierarchy

README.md (Template Users)
├── Quick Start
├── Requirements
├── Features Overview
└── Links to detailed docs
    ├── docs/LOCAL-DEVELOPMENT.md
    ├── docs/figma-to-wordpress/
    └── CLAUDE.md

CLAUDE.md (Claude Code Reference)
├── Project Overview
├── Critical Requirements (root-level folders)
├── Development Scripts
├── WordPress Standards
└── References (not duplicating):
    ├── Plugins: see .claude/PLUGINS-REFERENCE.md
    ├── Agents: see .claude/CUSTOM-AGENTS-GUIDE.md
    ├── Skills: see .claude/skills/README.md
    └── Figma: see docs/figma-to-wordpress/

.claude/ (Functional Files)
├── agents/                # Agent definitions (required by system)
├── skills/                # Skill definitions (required by system)
├── commands/              # Command definitions (required by system)
├── hooks/                 # Hook scripts (functional)
├── validation/            # Validation scripts (functional)
├── PLUGINS-REFERENCE.md   # Plugin command reference
├── CUSTOM-AGENTS-GUIDE.md # Agent catalog
└── AGENT-NAMING-GUIDE.md  # Agent disambiguation

Issue 5: Reports & Plans Mixed with Active Documentation

Current:

.claude/reports/:
├── figma-fse-implementation-plan.md
├── figma-fse-comparison.md
└── rcvmd-conversion-report.md

.claude/plans/:
└── figma-fse-rcvmd-conversion.md

Problem: Historical/development artifacts mixed with active documentation

Recommendation: Archive development history

archive/figma-development/:
├── implementation-plan.md         # Planning document
├── comparison.md                  # Analysis during development
├── rcvmd-conversion-plan.md       # March Medical plan
└── rcvmd-conversion-report.md     # March Medical results

Keep .claude/reports/ and .claude/plans/ empty or remove them.

.gitignore Issues

Current .gitignore Analysis

Line 3-7 Problem:

.claude/*                    # Ignore everything
!.claude/agents/             # Un-ignore agents
!.claude/skills/             # Un-ignore skills
!.claude/validation/         # Un-ignore validation
!.claude/*.md                # Un-ignore markdown files

Missing Un-ignore Patterns:

  • .claude/commands/ - Should be tracked (functional requirement)
  • .claude/hooks/ - Should be tracked (functional requirement)

Currently Ignored but Present:

  • .claude/logs/ - Correctly ignored (temporary)
  • .claude/reports/ - Should be removed (see Issue 5)
  • .claude/plans/ - Should be removed (see Issue 5)

Recommended .gitignore Changes

Add these un-ignore patterns:

.claude/*
!.claude/agents/
!.claude/skills/
!.claude/commands/          # ADD THIS
!.claude/hooks/             # ADD THIS
!.claude/validation/
!.claude/*.md

Explicitly ignore (redundant but clear):

# Claude Code temporary/user-specific files
.claude/logs/
.claude/settings.local.json
.claude/reports/            # Remove directory first
.claude/plans/              # Remove directory first

Additional Gitignore Recommendations

Consider adding:

# Documentation archive (if keeping historical docs)
/archive/

# Docker development files (if sensitive)
.env
docker-compose.override.yml

# Theme/plugin development artifacts
themes/*/node_modules/
themes/*/.DS_Store
plugins/*/node_modules/
plugins/*/.DS_Store

Proposed Reorganization Plan

Phase 1: Create New Structure (Non-Breaking)

  1. Create documentation directories:

    mkdir -p docs/figma-to-wordpress
mkdir -p archive/figma-development
mkdir -p archive/setup

  2. Consolidate Figma documentation:

    • Create docs/figma-to-wordpress/README.md (user guide)
    • Create docs/figma-to-wordpress/IMPLEMENTATION.md (technical)
    • Create docs/figma-to-wordpress/EXAMPLES.md (examples)
    • Move reports to archive/figma-development/
    • Move plans to archive/figma-development/

  3. Move historical documentation:

    • IMPLEMENTATION-SUMMARY.md → archive/development/
    • .claude/SETUP-COMPLETE.md → archive/setup/

  4. Update .gitignore:

    • Add !.claude/commands/
    • Add !.claude/hooks/
    • Add archive/ to ignored paths (if desired)

Phase 2: Clean Up Redundancy

  1. Streamline CLAUDE.md:

    • Remove plugin list (reference PLUGINS-REFERENCE.md)
    • Remove agent list (reference CUSTOM-AGENTS-GUIDE.md)
    • Remove skill list (reference .claude/skills/README.md)
    • Keep only WordPress standards and critical requirements
    • Target: 200 lines (currently 400+)

  2. Remove root-level files:

    • FIGMA-TO-FSE-AUTOMATION.md → Consolidated into docs/
    • IMPLEMENTATION-SUMMARY.md → archive/

  3. Clean up .claude/ directories:

    • Remove .claude/reports/ (after archiving)
    • Remove .claude/plans/ (after archiving)

Phase 3: Update Cross-References

  1. Update README.md to reference new structure
  2. Update CLAUDE.md to reference new locations
  3. Update skill files that reference moved documentation
  4. Test all documentation links

Recommended Final Structure

project-root/
├── README.md                       # Main entry point (template users)
├── CLAUDE.md                       # Claude Code reference (~200 lines)
├── LOCAL-DEVELOPMENT.md            # Or move to docs/
├── .gitignore                      # Updated with proper patterns
│
├── docs/
│   ├── LOCAL-DEVELOPMENT.md        # Docker setup (if moved)
│   └── figma-to-wordpress/
│       ├── README.md               # User guide + quick start
│       ├── IMPLEMENTATION.md       # Technical details
│       └── EXAMPLES.md             # Template examples
│
├── .claude/
│   ├── agents/                     # 27 agent definition files
│   ├── skills/                     # Skill definitions
│   │   ├── README.md               # Skills catalog
│   │   └── [8 skill directories]
│   ├── commands/                   # Command definitions
│   ├── hooks/                      # Hook scripts (tracked)
│   ├── validation/                 # Validation scripts
│   ├── logs/                       # Temporary (gitignored)
│   ├── settings.local.json         # User-specific (gitignored)
│   ├── PLUGINS-REFERENCE.md        # Plugin command reference
│   ├── CUSTOM-AGENTS-GUIDE.md      # Agent catalog
│   └── AGENT-NAMING-GUIDE.md       # Disambiguation
│
├── archive/                        # Historical documentation
│   ├── setup/
│   │   └── SETUP-COMPLETE.md
│   ├── development/
│   │   └── IMPLEMENTATION-SUMMARY.md
│   └── figma-development/
│       ├── implementation-plan.md
│       ├── comparison.md
│       ├── rcvmd-conversion-plan.md
│       └── rcvmd-conversion-report.md
│
├── themes/                         # Development themes (tracked)
├── plugins/                        # Development plugins (tracked)
├── mu-plugins/                     # Development mu-plugins (tracked)
└── scripts/                        # WordPress validation scripts
    └── README.md

Implementation Priority

High Priority (Do First):

  1. ✅ Fix .gitignore (add commands, hooks)
  2. ✅ Consolidate Figma docs (14 files → 3 files)
  3. ✅ Archive reports and plans
  4. ✅ Streamline CLAUDE.md (remove duplicated lists)

Medium Priority:

  1. Move IMPLEMENTATION-SUMMARY.md to archive
  2. Move SETUP-COMPLETE.md to archive
  3. Update cross-references in remaining docs
  4. Test all documentation links

Low Priority:

  1. Move LOCAL-DEVELOPMENT.md to docs/
  2. Create comprehensive index in README.md
  3. Add documentation contribution guidelines

Expected Benefits

After Reorganization:

  • Clarity: Single source of truth for each topic
  • Maintainability: Updates only needed in one place
  • Onboarding: Clear entry points for different users
  • Cleanliness: Root directory streamlined to 2-3 files
  • Version Control: Proper tracking of functional files
  • History: Development artifacts preserved but separated

Metrics:

  • Root markdown files: 5 → 2-3
  • Figma documentation files: 14 → 3
  • CLAUDE.md length: 400+ lines → ~200 lines
  • Redundant information: High → Minimal

Questions for Template Owner

  1. Archive directory: Should archive/ be tracked in git or gitignored?
  2. Historical reports: Keep or delete rcvmd-conversion reports?
  3. LOCAL-DEVELOPMENT.md: Keep in root or move to docs/?
  4. Agent pruning: Remove 16 non-WordPress agents from template?
  5. Setup documentation: Keep SETUP-COMPLETE.md for reference or archive?

Next Steps: Review recommendations and approve Phase 1 implementation.