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:

• Core Files - Verify critical system files exist

• Folder Structure - Check required directories

• Memory Files - Validate Memory/ content

• Navigation Files - Check framework-map.md and skill-map.md

• Projects - Validate all projects in 02-Projects/

• Skills - Validate all skills in 00-system/Skills/

• Map Integrity - Ensure maps match actual files

• Python Hooks - Run validation hooks (if available)

• Auto-Fix - Repair common issues automatically

• 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!