Validate Workspace Map

Ensure workspace-map.md stays synchronized with actual 04-workspace/ folder structure up to 3 levels deep.

Purpose

The workspace-map.md file helps AI understand your custom folder organization in 04-workspace/. When it becomes stale (folders added/removed/reorganized but not documented), AI navigation becomes unreliable.

This skill:

• Scans workspace structure 3 levels deep (root → level 1 → level 2 → level 3)

• Compares actual folders with documented folders at all levels

• Identifies mismatches (missing or extra folders, incorrect nesting)

• Provides detailed structure report with depth indicators

• Guides you through comprehensive updates

• Validates accuracy after changes

Improvements over v1:

• ✅ 3-layer deep scanning (vs 1 layer)

• ✅ Hierarchical validation (parent-child relationships)

• ✅ File detection (warns about files that should be documented)

• ✅ Depth indicators in reports (├──, │ ├──, │ │ ├──)

• ✅ Comprehensive documentation prompts for nested structures

When to use:

• You reorganized 04-workspace/ folders

• You notice AI can't find your folders

• During onboarding (Project 03, Task 5.6)

• As part of regular maintenance (via close-session)

Workflow

Step 1: Scan Actual Workspace Structure (3 Levels Deep)

Scan workspace recursively (up to 3 levels):

find 04-workspace -maxdepth 3 -type d | sort

Parse into hierarchical structure:

04-workspace/ ├── input/ │ ├── skills/ │ │ ├── examples/ │ │ └── templates/ │ └── docs/ ├── clients/ │ ├── acme/ │ │ ├── deliverables/ │ │ └── notes/ │ └── globex/ └── templates/

Also scan for important files (for documentation warnings):

find 04-workspace -maxdepth 3 -type f -name ".md" -o -name "README" | sort

Store:

• ACTUAL_STRUCTURE (tree with 3 levels)

• IMPORTANT_FILES (markdown/README files)

Exclude:

• Hidden folders (., .., .git, .DS_Store)

• workspace-map.md itself

• System folders

Time: 10 seconds

Step 2: Parse workspace-map.md (3 Levels Deep)

Read: 04-workspace/workspace-map.md

Extract documented structure:

From tree structure (in "Your Workspace Structure" section):

• Parse lines with ├── , │ ├── , │ │ ├── (depth indicators)

• Build hierarchical tree from indentation

• Capture folder descriptions (inline comments with # )

From folder descriptions (in "Folder Descriptions" section):

• Parse ### headers (level 1 folders)

• Parse #### headers (level 2 folders)

• Parse ##### headers (level 3 folders)

• Extract purpose, contents, and notes

Cross-reference both sections for completeness

Store:

• MAPPED_STRUCTURE (tree with 3 levels)

• MAPPED_DESCRIPTIONS (folder purposes and details)

Time: 10 seconds

Step 3: Deep Comparison (Hierarchical)

Compare at each level:

Level 1 (04-workspace/ direct children):

• Missing from map

• Extra in map (stale)

• Matches

Level 2 (within each level 1 folder):

• For each level 1 folder, compare children

• Track parent-child relationships

• Identify orphaned level 2 folders (parent missing)

Level 3 (within each level 2 folder):

• For each level 2 folder, compare children

• Validate full path accuracy

• Identify deeply nested mismatches

Identify:

• Missing folders (at each level)

• Extra folders (stale documentation at each level)

• Hierarchy issues (documented under wrong parent)

• Undocumented files (important .md files with no description)

• Perfect match (all levels accurate)

Time: 5 seconds

Step 4: Generate Comprehensive Report

Show detailed validation results at all 3 levels with clear depth indicators and actionable feedback.

Total Time Estimates

Scenarios:

• Perfect match (3 levels): ~20 seconds

• Minor updates (1-2 folders): 2-3 minutes

• Major reorganization (5+ folders): 5-7 minutes

• Deep restructure (many level 2-3 changes): 8-10 minutes

Integration

close-session Integration

This skill is automatically triggered during close-session. If mismatches found, prompts user to update.

Remember: Deep 3-level validation = Comprehensive AI navigation!