# Reference Patterns
# Optimized reference system with flattened hierarchy and automated validation

## Legend
| Symbol | Meaning | | Abbrev | Meaning |
|--------|---------|---|--------|---------|
| @common | universal patterns | | ref | reference |
| @cmd | command-specific | | val | validation |
| → | maps to | | alias | shortcut |

## Flattened Universal References

```yaml
# Direct references (2-layer max) replacing @common/* system
Universal_Patterns:
  legend: "shared/universal-constants.yml#Universal_Legend"
  flags: "shared/flag-inheritance.yml#Universal_Always"
  lifecycle: "shared/execution-patterns.yml#Standard_Lifecycle"
  success: "shared/universal-constants.yml#Success_Messages"
  header: "shared/command-patterns.yml#Command_Header"
  report: "shared/docs-patterns.yml#Standard_Notifications"
  research: "shared/research-patterns.yml#Mandatory_Research_Flows"
  exec-control: "shared/flag-inheritance.yml#Execution_Control"
  
Quality_Patterns:
  validation: "shared/quality-patterns.yml#Pre_Execution_Validation"
  severity: "shared/quality-patterns.yml#Severity_Framework"
  recovery: "shared/quality-patterns.yml#Recovery_Strategies"
  monitoring: "shared/quality-patterns.yml#Runtime_Monitoring"
  
Workflow_Patterns:
  chains: "shared/execution-patterns.yml#Chain_Execution_Patterns"
  git: "shared/execution-patterns.yml#Git_Integration_Patterns"
  checkpoints: "shared/execution-patterns.yml#Checkpoint_Management"
  mcp: "shared/execution-patterns.yml#MCP_Server_Registry"
  
Architecture_Patterns:
  ddd: "shared/architecture-patterns.yml#DDD_Building_Blocks"
  api: "shared/architecture-patterns.yml#REST_API_Patterns"
  security: "shared/security-patterns.yml#Security_Patterns"
  scaling: "shared/architecture-patterns.yml#Scalability_Patterns"
  
Documentation_Patterns:
  structure: "shared/docs-patterns.yml#Directory_Standards"
  formats: "shared/docs-patterns.yml#Format_Requirements"
  notifications: "shared/docs-patterns.yml#Output_Notifications"
  tasks: "shared/docs-patterns.yml#Task_File_Formatting"
```

## Command-Specific Pattern Groups

```yaml
# Optimized command patterns with direct references
Analysis_Commands:
  # analyze, scan, troubleshoot
  flags: "shared/flag-inheritance.yml#Analysis_Commands"
  patterns: "shared/command-patterns.yml#Analysis_Commands"
  quality: "shared/quality-patterns.yml#Command_Specific_Recovery"
  
Build_Commands:  
  # build, design, deploy
  flags: "shared/flag-inheritance.yml#Build_Commands"
  patterns: "shared/command-patterns.yml#Build_Commands"
  lifecycle: "shared/execution-patterns.yml#Command_Hooks"
  
Quality_Commands:
  # test, improve, cleanup
  flags: "shared/flag-inheritance.yml#Quality_Commands"
  control: "shared/quality-patterns.yml#Quality_Reports"
  monitoring: "shared/quality-patterns.yml#Runtime_Monitoring"
  
Operations_Commands:
  # deploy, migrate, git
  flags: "shared/flag-inheritance.yml#Operations_Commands"
  lifecycle: "shared/execution-patterns.yml#Git_Integration_Patterns"
  audit: "shared/execution-patterns.yml#Checkpoint_Management"
  
Documentation_Commands:
  # document, explain
  flags: "shared/flag-inheritance.yml#Documentation_Commands"
  templates: "shared/docs-patterns.yml#Format_Requirements"
  structure: "shared/docs-patterns.yml#Directory_Standards"
```

## Optimized Template Usage

```yaml
# Replace verbose @include patterns with direct references
Command_File_Templates:
  Standard_Header: |
    @legend
    @header
    @flags
    @exec-control
    
  Quality_Focus: |
    @legend  
    @header
    @flags
    @validation
    @monitoring
    
  Architecture_Focus: |
    @legend
    @header  
    @flags
    @ddd
    @api
    
  Documentation_Focus: |
    @legend
    @header
    @flags
    @structure
    @formats

# Simple expansion rules (no nesting)
Expansion_Rules:
  Pattern: "@{pattern_name}"
  Resolution: "Direct lookup in reference tables above"
  No_Nesting: "Single level expansion only"
  Fallback: "Use full path if pattern not found"
```

## Reference Validation System

```yaml
Validation_Rules:
  Reference_Integrity:
    Check_Targets: "Verify all referenced files and sections exist"
    Detect_Circular: "Prevent circular reference chains"
    Validate_Syntax: "Ensure proper @pattern format"
    Report_Broken: "List all broken references with locations"
    
  Auto_Validation:
    Startup_Check: "Validate all references on system startup"
    Git_Hook: "Validate before commits via pre-commit hook"
    File_Watch: "Monitor shared files for changes"
    Repair_Mode: "Auto-fix simple reference errors"
    
  Validation_Report:
    Location: ".claudedocs/validation/references-{timestamp}.md"
    Format: "Markdown with severity levels and fix suggestions"
    Sections: ["Summary", "Broken References", "Recommendations", "Auto-Fixes Applied"]
```

## File Organization

```yaml
Pattern_Files:
  Universal_Constants: "universal-constants.yml"
  Command_Patterns: "command-patterns.yml"
  Architecture: "architecture-patterns.yml"
  Security: "security-patterns.yml"
  Quality: "quality-patterns.yml"
  Execution: "execution-patterns.yml"
  Documentation: "docs-patterns.yml"
  
Usage:
  Direct_Reference: "See shared/[file].yml#[section]"
  No_Nesting: "Keep references simple and direct"
  Self_Contained: "Each command has complete information"
```

## Performance Optimizations

```yaml
Reference_Performance:
  Caching:
    Strategy: "Cache resolved references for session duration"
    Invalidation: "Clear cache when shared files change"
    Memory_Usage: "Limit cache size to prevent memory issues"
    
  Lazy_Loading:
    On_Demand: "Only resolve references when actually needed"
    Batch_Resolution: "Resolve multiple references in single operation"
    Prefetch: "Preload commonly used patterns"
    
  Token_Efficiency:
    Direct_Paths: "Use direct file paths instead of aliases where beneficial"
    Pattern_Inlining: "Inline small patterns instead of referencing"
    Compression: "Apply UltraCompressed mode to reference content"
    
Monitoring:
  Reference_Usage: "Track which patterns are used most frequently"
  Resolution_Time: "Monitor time to resolve references"
  Cache_Hit_Rate: "Measure caching effectiveness"
  Error_Frequency: "Track broken reference patterns"
  
Benefits:
  Token_Reduction: "~30% reduction in reference overhead"
  Complexity_Reduction: "2-layer max vs 3+ layer indirection"
  Maintainability: "Easier to trace and update references"
  Performance: "Faster resolution and lower memory usage"
```

## Integration Points

```yaml
Command_File_Usage:
  Standard_Commands: "Each command is self-contained"
  Organization: "Common patterns in shared files"
  Validation_Required: "All commands follow standard structure"
  
Framework_System:
  Direct_References: "Use explicit file paths"
  Error_Handling: "Clear documentation of patterns"
  Development_Mode: "Easy to understand and maintain"
  
Framework_Integration:
  Git_Hooks: "Automatic validation on commits and merges"
  CI_CD: "Reference integrity checks in build pipeline"
  Editor_Support: "Syntax highlighting and validation"
```

---
*Reference Patterns v4.0.0 - Optimized reference system with flattened hierarchy and automated validation*