# Config Validation System

## Legend
| Symbol | Meaning | | Abbrev | Meaning |
|--------|---------|---|--------|---------|
| → | leads to | | cfg | configuration |
| & | and/with | | val | validation |
| ✅ | valid/success | | req | required |
| ❌ | invalid/error | | dep | dependency |

## Validation Rules

```yaml
Core_Config_Files:
  Required_Files:
    - ~/.claude/CLAUDE.md
    - ~/.claude/RULES.md  
    - ~/.claude/PERSONAS.md
    - ~/.claude/MCP.md
    
  YAML_Syntax_Check:
    Tool: "yamllint --strict"
    Rules: "No syntax errors, proper indentation, valid structure"
    Action_On_Fail: "Block loading, show specific line errors"
    
  Cross_Reference_Validation:
    Persona_Command_Matrix:
      Check: "All personas reference valid commands"
      Example: "architect → /user:design --api (must exist)"
      
    MCP_Server_References:  
      Check: "All MCP flags reference available servers"
      Valid: "--c7 --seq --magic --pup"
      Invalid: "--unknown-mcp"
      
    Shared_Resource_Links:
      Check: "@see shared/file.yml references exist"
      Pattern: "@see shared/([^\\s]+)"
      Validation: "File exists & section valid"
      
    Command_Flag_Consistency:
      Check: "Universal flags defined consistently"
      Universal: "--plan --think --think-hard --ultrathink --uc"
      MCP: "--c7 --seq --magic --pup --no-mcp"
```

## Dependency Validation

```yaml
Command_Dependencies:
  Required_Sections:
    - Legend (w/ symbols used in file)
    - Command description
    - Examples
    - Deliverables
    
  Flag_Definitions:
    Check: "All flags mentioned have descriptions"
    Pattern: "--([a-z-]+)"
    Validation: "Flag documented in file or shared templates"
    
  MCP_Integration:
    Consistency: "MCP usage matches persona preferences"
    Example: "frontend persona → prefers --magic flag"
    
  Research_Requirements:
    Check: "All commands reference research-first.yml"
    Required: "@see shared/research-first.yml"
    
Shared_Resource_Dependencies:
  Template_Usage:
    Pattern: "@include shared/([^#]+)#([^\\s]+)"
    Validation: "Template file exists & section defined"
    
  Cross_References:
    Pattern: "@see shared/([^\\s]+)"
    Validation: "Referenced files exist & accessible"
    
  Symbol_Consistency:
    Check: "Symbols used match legend definitions"
    Validation: "All symbols (→ & w/ @) defined in legend"
```

## Validation Implementation

```yaml
Pre_Load_Checks:
  1_File_Existence:
    Check: "All required files present"
    Action: "Create missing w/ defaults or block"
    
  2_YAML_Syntax:
    Tool: "Built-in YAML parser"
    Report: "Line-specific syntax errors"
    
  3_Cross_References:
    Check: "All @see & @include links valid"  
    Report: "Broken references w/ suggestions"
    
  4_Consistency:
    Check: "Persona↔command↔MCP alignment"
    Report: "Inconsistencies w/ recommended fixes"
    
Runtime_Validation:
  Command_Execution:
    Check: "Requested command exists & valid"
    Check: "All flags recognized"
    Check: "MCP servers available"
    
  Context_Validation:
    Check: "Required dependencies present"
    Check: "Permissions adequate"
    Check: "No circular references"
    
Auto_Repair:
  Missing_Sections:
    Action: "Generate w/ templates"
    Example: "Missing legend → auto-generate from symbols used"
    
  Broken_References:
    Action: "Suggest alternatives or create stubs"
    Example: "@see missing-file.yml → create basic template"
    
  Outdated_Patterns:
    Action: "Suggest modernization"
    Example: "Old flag syntax → new standardized format"
```

## Validation Reports

```yaml
Report_Structure:
  Location: ".claudedocs/validation/config-validation-<timestamp>.md"
  Sections:
    - Executive Summary (✅❌ counts)
    - File-by-file detailed results
    - Cross-reference matrix
    - Recommended actions
    - Auto-repair options
    
Severity_Levels:
  CRITICAL: "Syntax errors, missing required files"
  HIGH: "Broken cross-references, invalid MCP refs"  
  MEDIUM: "Missing documentation, inconsistent patterns"
  LOW: "Style issues, optimization opportunities"
  
Actions_By_Severity:
  CRITICAL: "Block loading until fixed"
  HIGH: "Warn & continue w/ degraded functionality"
  MEDIUM: "Note in report, suggest fixes"
  LOW: "Background report only"
```

## Integration Points

```yaml
SuperClaude_Startup:
  1_Run_Validation: "Before loading any configs"
  2_Report_Issues: "Show summary to user"
  3_Auto_Repair: "Fix what can be auto-repaired"
  4_Block_Critical: "Don't load if critical errors"
  
Command_Execution:
  Pre_Execution: "Validate command & flags exist"
  Runtime: "Check dependencies available"
  Post_Execution: "Validate output format"
  
Config_Updates:
  On_File_Change: "Re-validate affected files"
  On_Install: "Full validation before deployment"
  Periodic: "Weekly validation health check"
  
Developer_Tools:
  CLI_Command: "/user:validate --config"
  Report_Command: "/user:validate --report"
  Fix_Command: "/user:validate --auto-repair"
```

## Implementation Examples

```yaml
Basic_Usage:
  Manual: "validate_config() before load"
  Automatic: "Built into SuperClaude startup"
  Reporting: "Generate .claudedocs/validation/ reports"
  
Error_Examples:
  Syntax_Error: |
    "YAML syntax error in PERSONAS.md line 42:
     Expected scalar, found sequence
     Fix: Check indentation & structure"
     
  Broken_Reference: |
    "@see shared/missing-file.yml not found
     Suggestions: 
     - Create missing-file.yml w/ template
     - Fix reference to shared/existing-file.yml"
     
  Inconsistency: |
    "Persona 'frontend' references --magic flag
     but MCP.md shows Magic server disabled
     Fix: Enable Magic server or update persona"
```

---
*Config Validator v1.0 - Automated validation for SuperClaude configuration integrity*