appiq-solution 1.1.0 → 1.3.0

package/#Tools/SuperClaude/.claude/commands/shared/error-handling.yml

@@ -0,0 +1,341 @@
+# Error Handling & Recovery System
+
+## Legend
+| Symbol | Meaning | | Abbrev | Meaning |
+|--------|---------|---|--------|---------|
+| 🔄 | retry/recovery | | err | error |
+| ⚠ | warning/caution | | rec | recovery |
+| ✅ | success/fixed | | ctx | context |
+| 🔧 | repair/fix | | fail | failure |
+
+## Error Classification & Response
+
+```yaml
+Severity_Levels:
+  CRITICAL [10]: Data loss, security breach, prod down
+    Response: Immediate stop, alert, rollback, incident response
+    Recovery: Manual intervention required, full investigation
+    
+  HIGH [7-9]: Build failure, test failure, deployment issues
+    Response: Stop workflow, notify user, suggest fixes
+    Recovery: Automated retry w/ backoff, alternative paths
+    
+  MEDIUM [4-6]: Warning conditions, perf degradation
+    Response: Continue w/ warning, log for later review
+    Recovery: Attempt optimization, monitor for escalation
+    
+  LOW [1-3]: Info messages, style violations, minor optimizations
+    Response: Note in output, continue execution
+    Recovery: Background fixes, cleanup on completion
+
+Error_Categories:
+  Transient:
+    Network_Timeouts: "MCP server unreachable, API timeouts"
+    Resource_Busy: "File locked, system overloaded"
+    Rate_Limits: "API quota exceeded, temporary blocks"
+    Strategy: Exponential backoff retry, circuit breaker pattern
+    
+  Permanent:
+    Syntax_Errors: "Invalid code, malformed input"
+    Permission_Denied: "Access restrictions, auth failures"
+    Not_Found: "Missing files, invalid paths"
+    Strategy: No retry, immediate fallback or user guidance
+    
+  Context:
+    Configuration: "Missing env vars, incorrect settings"
+    State_Conflicts: "Dirty working tree, merge conflicts"
+    Version_Mismatch: "Incompatible versions, deprecated APIs"
+    Strategy: Validation, helpful error msgs, setup guidance
+    
+  Resource:
+    Memory: "Out of memory, insufficient resources"
+    Disk_Space: "Storage full, temp space unavailable"
+    API_Limits: "Rate limits, quota exceeded"
+    Strategy: Resource monitoring, cleanup, queue management
+```
+
+## Intelligent Retry Strategies
+
+```yaml
+Retry_Logic:
+  Exponential_Backoff:
+    Base_Delay: "1 second"
+    Max_Delay: "60 seconds"
+    Max_Attempts: "3 for transient, 1 for permanent"
+    Jitter: "±25% randomization to avoid thundering herd"
+    
+  Adaptive_Strategy:
+    Network_Errors: "Retry w/ longer timeout"
+    Rate_Limits: "Wait for reset period + retry"
+    Resource_Busy: "Short delay + retry w/ alternative"
+    Permanent: "No retry, immediate fallback"
+
+Circuit_Breaker:
+  Failure_Threshold: "3 consecutive failures"
+  Recovery_Time: "5 minutes before re-enabling"
+  Health_Check: "Lightweight test before full retry"
+```
+
+## MCP Server Failover
+
+```yaml
+Failover_Hierarchy:
+  Context7_Failure:
+    Primary: "C7 documentation lookup"
+    Fallback_1: "WebSearch official docs"
+    Fallback_2: "Local cache if available"
+    Fallback_3: "Continue w/ warning + note limitation"
+    
+  Sequential_Failure:
+    Primary: "Sequential thinking server"
+    Fallback_1: "Native step-by-step analysis"
+    Fallback_2: "Simplified linear approach"
+    Fallback_3: "Manual breakdown w/ user input"
+    
+  Magic_Failure:
+    Primary: "Magic UI component generation"
+    Fallback_1: "Search existing components in project"
+    Fallback_2: "Generate basic template manually"
+    Fallback_3: "Provide implementation guidance"
+    
+  Puppeteer_Failure:
+    Primary: "Browser automation & testing"
+    Fallback_1: "Manual test instructions"
+    Fallback_2: "Static analysis alternatives"
+    Fallback_3: "Skip browser-specific operations"
+
+Server_Health_Monitoring:
+  Availability_Check:
+    Frequency: "Every 5 minutes during active use"
+    Timeout: "3 seconds per check"
+    Circuit_Breaker: "Disable after 3 consecutive failures"
+    Recovery_Check: "Re-enable after 5 minutes"
+    
+  Performance_Degradation:
+    Slow_Response: ">30s response time"
+    Action: "Switch to faster alternative if available"
+    Notification: "Inform user of performance impact"
+```
+
+## Recovery Strategies
+
+```yaml
+Automatic_Recovery:
+  Retry_Mechanisms:
+    Simple: "Up to 3 attempts with 1s delay"
+    Exponential: "1s, 2s, 4s, 8s delays with jitter"
+    Circuit_Breaker: "Stop retries after threshold failures"
+    
+  Fallback_Patterns:
+    Alternative_Commands: "Use native tools if MCP fails"
+    Degraded_Functionality: "Skip non-essential features"
+    Cached_Results: "Use previous successful outputs"
+    
+  State_Management:
+    Checkpoints: "Save state before risky operations"
+    Rollback: "Automatic revert to last known good state"
+    Cleanup: "Remove partial results on failure"
+
+Manual_Recovery:
+  User_Guidance:
+    Clear_Error_Messages: "What failed, why, how to fix"
+    Action_Items: "Specific steps user can take"
+    Documentation_Links: "Relevant help resources"
+    
+  Intervention_Points:
+    Confirmation: "Ask before destructive operations"
+    Override: "Allow user to skip validation warnings"
+    Custom: "Accept user-provided alternative approaches"
+    
+  Recovery_Tools:
+    Diagnostic: "Commands to investigate failures"
+    Repair: "Automated fixes for common issues"
+    Reset: "Return to clean state for fresh start"
+```
+
+## Context Preservation
+
+```yaml
+Operation_Checkpoints:
+  Before_Risky_Operations:
+    Create_Checkpoint: "Save current state before destructive ops"
+    Include: "File states, working directory, command context"
+    Location: ".claudedocs/checkpoints/checkpoint-<timestamp>"
+    
+  During_Command_Chains:
+    Intermediate_Results: "Save results after each successful step"
+    Context_Handoff: "Pass validated context to next command"
+    Rollback_Points: "Mark safe restoration points"
+    
+  Failure_Recovery:
+    Partial_Completion: "Preserve completed work"
+    State_Analysis: "Determine safe rollback point"
+    User_Options: "Present recovery choices"
+
+Context_Resilience:
+  Session_State:
+    Persistent_Storage: "Maintain state across interruptions"
+    Auto_Save: "Periodic context snapshots"
+    Recovery: "Restore from last known good state"
+    
+  Command_Chain_Recovery:
+    Failed_Step_Isolation: "Don't lose previous successful steps"
+    Alternative_Paths: "Suggest different approaches for failed step"
+    Partial_Results: "Use completed work in recovery strategy"
+```
+
+## Proactive Error Prevention
+
+```yaml
+Pre_Execution_Validation:
+  Environment_Check:
+    Required_Tools: "Verify dependencies before starting"
+    Permissions: "Check access rights for planned operations"
+    Disk_Space: "Ensure adequate space for outputs"
+    Network: "Verify connectivity for remote operations"
+    
+  Conflict_Detection:
+    File_Locks: "Check for locked files before editing"
+    Git_State: "Verify clean working tree for git ops"
+    Process_Conflicts: "Detect conflicting background processes"
+    
+  Resource_Availability:
+    Memory_Usage: "Ensure adequate RAM for large operations"
+    CPU_Load: "Warn if system under heavy load"
+    Token_Budget: "Estimate token usage vs available quota"
+
+Risk_Assessment:
+  Operation_Scoring:
+    Data_Loss_Risk: "1-10 scale based on destructiveness"
+    Reversibility: "Can operation be undone?"
+    Scope_Impact: "How many files/systems affected?"
+    
+  Mitigation_Requirements:
+    High_Risk: "Require explicit confirmation + backup"
+    Medium_Risk: "Warn user + create checkpoint"
+    Low_Risk: "Proceed w/ monitoring"
+```
+
+## Command-Specific Recovery
+
+```yaml
+Build_Failures:
+  Clean_Retry: "Remove artifacts, clear cache, rebuild"
+  Dependency_Issues: "Update lockfiles, reinstall packages"
+  Compilation_Errors: "Suggest fixes, alternative approaches"
+  
+Test_Failures:
+  Flaky_Tests: "Retry failed tests, identify unstable tests"
+  Environment_Issues: "Reset test state, check prerequisites"
+  Coverage_Gaps: "Generate missing tests, update thresholds"
+  
+Deploy_Failures:
+  Health_Check_Failures: "Rollback, investigate logs"
+  Resource_Constraints: "Scale up, optimize deployment"
+  Configuration_Issues: "Validate settings, check secrets"
+  
+Analysis_Failures:
+  Tool_Unavailable: "Fallback to alternative analysis tools"
+  Large_Codebase: "Reduce scope, batch processing"
+  Permission_Issues: "Guide user through access setup"
+```
+
+## Enhanced Error Reporting
+
+```yaml
+Intelligent_Error_Messages:
+  Root_Cause_Analysis:
+    Technical_Details: "Specific error codes, stack traces"
+    User_Context: "What user was trying to accomplish"
+    Environmental_Factors: "System state, recent changes"
+    
+  Actionable_Guidance:
+    Immediate_Steps: "What user can do right now"
+    Alternative_Approaches: "Different ways to achieve goal"
+    Prevention: "How to avoid this error in future"
+    
+  Context_Preservation:
+    Session_Info: "Command history, current state"
+    Relevant_Files: "Which files were being processed"
+    System_State: "Git status, dependency versions"
+
+Error_Learning:
+  Pattern_Recognition:
+    Frequent_Issues: "Track commonly occurring errors"
+    User_Patterns: "Learn user-specific failure modes"
+    System_Patterns: "Identify environment-specific issues"
+    
+  Adaptive_Responses:
+    Personalized_Suggestions: "Based on user's history"
+    Proactive_Warnings: "Predict likely issues"
+    Automated_Fixes: "Apply known solutions automatically"
+```
+
+## Integration with Commands
+
+```yaml
+Pre_Execution_Validation:
+  Prerequisites: "Check required tools, permissions, resources"
+  Environment: "Validate configuration, network connectivity"
+  State: "Ensure clean starting state, no conflicts"
+  
+During_Execution:
+  Monitoring: "Track progress, resource usage, early warnings"
+  Checkpointing: "Save state at critical milestones"
+  Health_Checks: "Validate system state during long operations"
+  
+Post_Execution:
+  Verification: "Confirm expected outcomes achieved"
+  Cleanup: "Remove temporary files, release resources"
+  Reporting: "Document successes, failures, lessons learned"
+  
+Error_Reporting_Format:
+  Structured: "Consistent error message format across commands"
+  Actionable: "Include specific steps for resolution"
+  Contextual: "Provide relevant system and environment information"
+  Traceable: "Include operation ID for troubleshooting"
+```
+
+## Configuration & Customization
+
+```yaml
+User_Preferences:
+  Recovery_Style: "Conservative (safe) vs Aggressive (fast)"
+  Retry_Limits: "Maximum attempts for different error types"
+  Notification: "How and when to alert user of issues"
+  Automation_Level: "How much recovery to attempt automatically"
+  
+Project_Settings:
+  Critical_Operations: "Commands that require extra safety"
+  Acceptable_Risk: "Tolerance for failures in development vs production"
+  Resource_Limits: "Maximum time, memory, network usage"
+  Dependencies: "Critical external services that must be available"
+  
+Environment_Adaptation:
+  Development: "More aggressive retries, helpful error messages"
+  Staging: "Balanced approach, thorough logging"
+  Production: "Conservative recovery, immediate alerting"
+  CI_CD: "Fast failure, detailed diagnostic information"
+```
+
+## Usage Examples
+
+```yaml
+Network_Failure_Scenario:
+  Error: "Context7 server timeout during docs lookup"
+  Recovery: "Auto-fallback to WebSearch → local cache"
+  User_Experience: "⚠ Using cached docs (Context7 unavailable)"
+  
+File_Lock_Scenario:
+  Error: "Cannot edit file (locked by another process)"
+  Recovery: "Wait 5s → retry → suggest alternatives"
+  User_Experience: "Retrying in 5s... or try manual edit"
+  
+Command_Chain_Failure:
+  Error: "Step 3 of 5 fails in build workflow"
+  Recovery: "Preserve steps 1-2, suggest alternatives for 3"
+  User_Experience: "Build partially complete. Alternative approaches: ..."
+```
+
+---
+*Error Handling v1.0 - Comprehensive error recovery and resilience for SuperClaude*

package/#Tools/SuperClaude/.claude/commands/shared/evidence.yml

@@ -0,0 +1,75 @@
+# Evidence & Verification Patterns
+
+## Measurement Standards
+
+```yaml
+Replace Hard Values:
+  Bad: "75% perf improvement"
+  Good: "<measured>% improvement"
+  Best: "<baseline>→<current> (<delta>%)"
+
+Placeholders:
+  <measured_value>: Actual measurement
+  <calculated_result>: Computed outcome
+  <baseline>: Starting point
+  <current>: Current state
+  <delta>: Change amount
+  <threshold>: Target value
+```
+
+## Verification Requirements
+
+```yaml
+Perf Claims:
+  Required: Measurement method
+  Format: "Measured via <tool>: <metric>"
+  Example: "Measured via Lighthouse: FCP <value>ms"
+
+Quality Metrics:
+  Coverage: "Test coverage: <measured>%"
+  Complexity: "Cyclomatic: <calculated>"
+  Duplication: "DRY score: <measured>%"
+
+Time Estimates:
+  Format: "<min>-<max> <unit> (±<uncertainty>%)"
+  Based on: Historical data|Complexity analysis
+
+Implementation Sources:
+  Required: Documentation reference for external libraries
+  Format: "Source: <official docs URL or reference>"
+  Placement: Above implementation using pattern
+  
+  Examples:
+    Good: "// Source: React docs - useState hook"
+    Bad: "// Common React pattern"
+    
+  No Source = Block: External library usage without documentation
+```
+
+## Evidence Collection
+
+```yaml
+Before: Baseline measurement
+During: Progress tracking  
+After: Final measurement
+Delta: Calculate improvement
+
+Tools:
+  Performance: Lighthouse|DevTools|APM
+  Code: Coverage reports|Linters|Analyzers
+  Time: Git history|Task tracking
+```
+
+## Reporting Format
+
+```yaml
+Pattern:
+  Claim: What improved
+  Evidence: How measured
+  Result: Specific values
+  
+Example:
+  Claim: "Optimized query performance"
+  Evidence: "EXPLAIN ANALYZE before/after"
+  Result: "<before>ms → <after>ms (<delta>% faster)"
+```

package/#Tools/SuperClaude/.claude/commands/shared/execution-lifecycle.yml

@@ -0,0 +1,277 @@
+# Execution Lifecycle & Common Hooks
+
+## Legend
+| Symbol | Meaning | | Abbrev | Meaning |
+|--------|---------|---|--------|---------|
+| ▶ | start/begin | | exec | execution |
+| ⏸ | pause/checkpoint | | val | validation |
+| ⏹ | stop/end | | ver | verification |
+| 🔄 | cycle/repeat | | cln | cleanup |
+
+## Universal Execution Phases
+
+```yaml
+Standard_Lifecycle:
+  Pre_Execution:
+    Phase: "Validation and preparation"
+    Duration: "5-15% of total execution time"
+    Critical: "Prevent issues before they occur"
+    
+  During_Execution:
+    Phase: "Core operation execution"
+    Duration: "70-85% of total execution time"
+    Critical: "Monitor progress and handle errors"
+    
+  Post_Execution:
+    Phase: "Cleanup and verification"
+    Duration: "10-15% of total execution time"
+    Critical: "Ensure completion and clean state"
+
+Phase_Transitions:
+  Pre → During: "All validations pass"
+  During → Post: "Core operation completes (success or controlled failure)"
+  Post → Complete: "Cleanup verified, results confirmed"
+  Any → Error: "Unrecoverable error triggers error handling"
+  Any → Pause: "User interruption or checkpoint trigger"
+```
+
+## Pre-Execution Hooks
+
+```yaml
+Environment_Validation:
+  System_Requirements:
+    - Check required tools availability
+    - Verify sufficient system resources
+    - Validate network connectivity (if needed)
+    - Confirm adequate disk space
+    
+  Permission_Checks:
+    - Verify file system permissions
+    - Check git repository access
+    - Validate API credentials (if needed)
+    - Confirm write access to output directories
+    
+  State_Validation:
+    - Ensure clean working tree (for git operations)
+    - Check for file locks
+    - Verify no conflicting processes
+    - Validate prerequisite operations completed
+
+Dependency_Verification:
+  Tool_Availability:
+    Required_Tools: "Tools marked as required for operation"
+    Optional_Tools: "Tools that enhance but don't block operation"
+    Fallback_Tools: "Alternative tools if primary unavailable"
+    
+  File_Dependencies:
+    Input_Files: "Files that must exist for operation"
+    Configuration_Files: "Config files that affect operation"
+    Template_Files: "Templates needed for generation"
+    
+  Service_Dependencies:
+    MCP_Servers: "Required MCP servers for operation"
+    External_APIs: "External services needed"
+    Database_Connections: "DB access if required"
+
+Risk_Assessment:
+  Operation_Classification:
+    Data_Loss_Risk: "Scale 1-10 based on destructiveness"
+    Reversibility: "Can operation be undone automatically?"
+    Scope_Impact: "How many files/systems affected?"
+    
+  Safety_Requirements:
+    High_Risk: "Require explicit confirmation + backup"
+    Medium_Risk: "Create checkpoint + warn user"
+    Low_Risk: "Proceed with monitoring"
+    
+Preparation_Actions:
+  Backup_Creation:
+    Critical_Files: "Files that will be modified"
+    System_State: "Current git state, file timestamps"
+    Configuration: "Relevant config before changes"
+    
+  Context_Capture:
+    Current_State: "Working directory, git branch, file states"
+    User_Context: "Active persona, command flags, session history"
+    Environment: "Relevant environment variables, tool versions"
+```
+
+## During-Execution Hooks
+
+```yaml
+Progress_Monitoring:
+  Real_Time_Tracking:
+    Operation_Progress: "Percentage completion where measurable"
+    Resource_Usage: "CPU, memory, disk, network utilization"
+    Error_Frequency: "Number and types of errors encountered"
+    Performance_Metrics: "Speed, efficiency, token usage"
+    
+  Checkpoint_Creation:
+    Automatic_Triggers:
+      - Major phase completion
+      - Before risky operations
+      - Regular intervals (time-based)
+      - Resource threshold warnings
+    Manual_Triggers:
+      - User pause request
+      - Error recovery points
+      - External interruption
+      
+  Health_Monitoring:
+    System_Health:
+      - Available resources
+      - Tool responsiveness
+      - Network connectivity
+      - File system status
+    Operation_Health:
+      - Progress rate
+      - Error patterns
+      - Quality indicators
+      - User satisfaction signals
+
+Error_Handling_Integration:
+  Error_Detection:
+    Immediate: "Critical errors that require immediate stop"
+    Recoverable: "Errors that can be retried or worked around"
+    Warning: "Issues that should be logged but don't block"
+    
+  Recovery_Actions:
+    Automatic_Retry: "Transient errors with exponential backoff"
+    Fallback_Methods: "Alternative approaches when primary fails"
+    User_Guidance: "When manual intervention needed"
+    
+Adaptive_Optimization:
+  Performance_Adjustment:
+    Slow_Operations: "Switch to faster tools/methods"
+    High_Resource_Usage: "Reduce scope or batch operations"
+    Token_Efficiency: "Enable compression or caching"
+    
+  Strategy_Adjustment:
+    Success_Pattern_Learning: "Adapt based on what works"
+    Failure_Pattern_Avoidance: "Learn from what doesn't work"
+    User_Preference_Adaptation: "Adjust to user's working style"
+```
+
+## Post-Execution Hooks
+
+```yaml
+Result_Verification:
+  Output_Validation:
+    Expected_Files: "Verify all expected outputs were created"
+    File_Integrity: "Check file contents and formats"
+    Quality_Checks: "Validate output meets requirements"
+    
+  System_State_Check:
+    Git_Status: "Verify repository in expected state"
+    File_Permissions: "Check file access rights"
+    Process_State: "Ensure no hanging processes"
+    
+Success_Confirmation:
+  Objective_Achievement:
+    Primary_Goals: "Did operation achieve stated objectives?"
+    Quality_Standards: "Does output meet quality requirements?"
+    User_Satisfaction: "Any user corrections or interruptions?"
+    
+  Metrics_Collection:
+    Performance_Data: "Execution time, resource usage, efficiency"
+    Quality_Metrics: "Error rate, retry count, success indicators"
+    User_Experience: "Interruptions, corrections, satisfaction signals"
+
+Cleanup_Operations:
+  Temporary_Resources:
+    Temp_Files: "Remove temporary files created during operation"
+    Cache_Cleanup: "Clear expired cache entries"
+    Lock_Release: "Release any file or resource locks"
+    
+  System_Restoration:
+    Working_Directory: "Restore original working directory"
+    Environment_Variables: "Reset any temporary env vars"
+    Process_Cleanup: "Terminate any background processes"
+    
+  Resource_Release:
+    Memory_Cleanup: "Free allocated memory"
+    Network_Connections: "Close unnecessary connections"
+    File_Handles: "Close all opened files"
+
+Documentation_Update:
+  Operation_Log:
+    Execution_Record: "What was done, when, and how"
+    Performance_Metrics: "Time, resources, efficiency data"
+    Issues_Encountered: "Problems and how they were resolved"
+    
+  State_Updates:
+    Project_State: "Update project status/progress"
+    Configuration: "Update configs if changed"
+    Dependencies: "Note any new dependencies added"
+```
+
+## Lifecycle Integration Patterns
+
+```yaml
+Command_Integration:
+  Template_Usage:
+    Pre_Execution: "@include shared/execution-lifecycle.yml#Pre_Execution"
+    During_Execution: "@include shared/execution-lifecycle.yml#Progress_Monitoring"
+    Post_Execution: "@include shared/execution-lifecycle.yml#Cleanup_Operations"
+    
+  Phase_Customization:
+    Command_Specific: "Commands can override default hooks"
+    Additional_Hooks: "Commands can add specific validation/cleanup"
+    Skip_Phases: "Commands can skip irrelevant phases"
+
+Error_Recovery_Integration:
+  Checkpoint_Strategy:
+    Pre_Phase: "Create checkpoint before each major phase"
+    Mid_Phase: "Create checkpoints during long operations"
+    Recovery_Points: "Well-defined rollback points"
+    
+  Error_Escalation:
+    Phase_Failure: "How to handle failure in each phase"
+    Rollback_Strategy: "How to undo partial work"
+    User_Notification: "What to tell user about failures"
+
+Performance_Integration:
+  Timing_Collection:
+    Phase_Duration: "Track time spent in each phase"
+    Bottleneck_Identification: "Identify slow phases"
+    Optimization_Opportunities: "Where to focus improvements"
+    
+  Resource_Monitoring:
+    Peak_Usage: "Maximum resource usage during operation"
+    Efficiency_Metrics: "Resource usage vs. output quality"
+    Scaling_Behavior: "How resource usage scales with operation size"
+```
+
+## Customization Framework
+
+```yaml
+Hook_Customization:
+  Override_Points:
+    Before_Phase: "Custom actions before standard phase"
+    Replace_Phase: "Complete replacement of standard phase"
+    After_Phase: "Custom actions after standard phase"
+    
+  Conditional_Execution:
+    Environment_Based: "Different hooks for dev/staging/prod"
+    Operation_Based: "Different hooks for different operation types"
+    User_Based: "Different hooks based on user preferences"
+
+Extension_Points:
+  Additional_Validation:
+    Custom_Checks: "Project-specific validation rules"
+    External_Validation: "Integration with external systems"
+    Policy_Enforcement: "Organizational policy checks"
+    
+  Enhanced_Monitoring:
+    Custom_Metrics: "Project-specific performance metrics"
+    External_Reporting: "Integration with monitoring systems"
+    Alert_Integration: "Custom alerting rules"
+    
+  Specialized_Cleanup:
+    Project_Cleanup: "Project-specific cleanup routines"
+    External_Cleanup: "Integration with external systems"
+    Compliance_Actions: "Regulatory compliance cleanup"
+```
+
+---
+*Execution Lifecycle v1.0 - Common hooks and patterns for consistent SuperClaude operation execution*