abdullahbeam/validate-system

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!