abdullahbeam/update-workspace-map

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:

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

   • Parse lines with ├──, │ ├──, │ │ ├── (depth indicators)
   • Build hierarchical tree from indentation
   • Capture folder descriptions (inline comments with #)

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

3. 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!