Validate System

Check system integrity, auto-fix issues, validate maps, and run optional Python validation hooks.

Purpose

The validate-system skill performs comprehensive system health checks, validates structural integrity, checks navigation map accuracy, runs optional Python validation hooks, and attempts to auto-fix common issues. Use this skill when navigation seems stale, after manual file changes, or as periodic maintenance.

Key Features:

• •Comprehensive Checks: Core files, structure, memory, navigation, projects, skills
• •Map Integrity Validation: Ensures skill-map.md and project-map.md are accurate
• •Python Hooks: Runs automated validators (optional, graceful skip if unavailable)
• •Auto-Fix: Regenerates navigation, recreates templates, repairs structure
• •Detailed Reporting: Clear report of checks, issues, and fixes

Time Estimate: <10 seconds for full validation

Workflow

Step 1: Initialize TodoList

Create TodoWrite with all validation steps:

- [ ] Check core files
- [ ] Check folder structure
- [ ] Check memory files
- [ ] Check navigation files
- [ ] Validate projects
- [ ] Validate skills
- [ ] Check map integrity
- [ ] Run Python hooks (if available)
- [ ] Auto-fix issues
- [ ] Generate report
- [ ] Display report
- [ ] Close session to save progress

Mark tasks complete as you finish each step.

Step 2: Execute Validation Workflow

This skill performs comprehensive system validation with the following checks:

1. •Core Files - Verify critical system files exist
2. •Folder Structure - Check required directories
3. •Memory Files - Validate Memory/ content
4. •Navigation Files - Check framework-map.md and skill-map.md
5. •Projects - Validate all projects in 02-Projects/
6. •Skills - Validate all skills in 00-system/Skills/
7. •Map Integrity - Ensure maps match actual files
8. •Python Hooks - Run validation hooks (if available)
9. •Auto-Fix - Repair common issues automatically
10. •Report - Generate and display comprehensive report

Detailed validation steps: See references/validation-checks.md

Report templates: See references/report-templates.md

Time Estimate: <10 seconds for full validation

Final Step: Close Session

Automatically trigger the close-session skill:

Auto-triggering close-session to save progress...

This ensures all validation results and any auto-fixes are properly saved to memory.

Error Handling

Critical Files Missing

Scenario: framework-map.md, orchestrator.md, or claude.md missing

Action:

• •Report as CRITICAL ERROR
• •Cannot auto-fix (system corrupted)
• •Suggest: "Your system appears corrupted. Please restore from backup or reinstall Nexus-v3."
• •Do NOT proceed with auto-fixes (unsafe)

Python Hook Crashes

Scenario: Python hook script crashes or returns invalid JSON

Action:

• •Catch error gracefully
• •Report: "Hook {name} crashed: {error}"
• •Add to issues list
• •Continue with other hooks (don't block validation)

Cannot Write to Files

Scenario: Auto-fix fails due to file permission issues

Action:

• •Report: "Cannot write to {file}: {error}"
• •Add to manual fix list
• •Provide manual instructions
• •Continue with other auto-fixes

Corrupted Memory Files

Scenario: Memory/ files exist but are not valid markdown

Action:

• •Report: "{file} is corrupted (invalid markdown)"
• •Offer: "Replace with empty template? This will lose current content."
• •Wait for user confirmation
• •IF confirmed → Replace with template
• •IF declined → Add to manual fix list

Empty Projects/ Folder

Scenario: Projects/ exists but is empty (only during first-time setup)

Action:

• •Report: "Projects/ folder is empty (no projects yet)"
• •Note: "This is normal for new users."
• •Suggest: "Say 'create project' to start your first project!"
• •Mark as INFO (not an error)

Empty Skills/ Folder

Scenario: Skills/ exists but is empty

Action:

• •Report: "No user skills found (Skills/ folder empty)"
• •Note: "This is normal if you haven't created any skills yet."
• •Suggest: "Run create-skill to add your first skill!"
• •Mark as INFO (not an error)

Notes

When to Run validate-system:

• •After manual file edits
• •When navigation seems stale or inaccurate
• •After accidentally deleting files
• •As periodic maintenance (weekly/monthly)
• •When system behavior seems off

Auto-Fix Safety:

• •Only fixes non-destructive issues
• •Never deletes user content
• •Creates templates, regenerates navigation
• •Critical issues require manual intervention

Python Hooks:

• •Completely optional (system works without them)
• •Provide deeper automated validation
• •Gracefully skip if Python not available
• •Custom hooks can be added to 00-system/hooks/

Hook JSON Format:

{
  "valid": true/false,
  "errors": [
    {"file": "path", "line": 42, "message": "error description", "severity": "error"}
  ],
  "warnings": [
    {"file": "path", "line": 15, "message": "warning description", "severity": "warning"}
  ]
}

Map Integrity Importance:

• •skill-map.md MUST match Skills/ folder
• •02-projects/project-map.md MUST match Projects/ folder
• •Dead links break navigation
• •close-session maintains integrity automatically

Validation Frequency:

• •Run when suspicious: anytime something feels off
• •Run after manual changes: edited files outside skills
• •Run periodically: weekly or monthly maintenance
• •NOT needed after normal skill/project usage (close-session handles it)

Integration with close-session:

• •close-session automatically maintains map integrity
• •validate-system catches issues between sessions
• •Both work together for system health

Remember: validate-system is your system health check. Run it when things seem off, and let it auto-fix what it can!