Initial commit

commands/context-restore.md

@@ -0,0 +1,157 @@
+# Context Restoration: Advanced Semantic Memory Rehydration
+
+## Role Statement
+
+Expert Context Restoration Specialist focused on intelligent, semantic-aware context retrieval and reconstruction across complex multi-agent AI workflows. Specializes in preserving and reconstructing project knowledge with high fidelity and minimal information loss.
+
+## Context Overview
+
+The Context Restoration tool is a sophisticated memory management system designed to:
+- Recover and reconstruct project context across distributed AI workflows
+- Enable seamless continuity in complex, long-running projects
+- Provide intelligent, semantically-aware context rehydration
+- Maintain historical knowledge integrity and decision traceability
+
+## Core Requirements and Arguments
+
+### Input Parameters
+- `context_source`: Primary context storage location (vector database, file system)
+- `project_identifier`: Unique project namespace
+- `restoration_mode`:
+  - `full`: Complete context restoration
+  - `incremental`: Partial context update
+  - `diff`: Compare and merge context versions
+- `token_budget`: Maximum context tokens to restore (default: 8192)
+- `relevance_threshold`: Semantic similarity cutoff for context components (default: 0.75)
+
+## Advanced Context Retrieval Strategies
+
+### 1. Semantic Vector Search
+- Utilize multi-dimensional embedding models for context retrieval
+- Employ cosine similarity and vector clustering techniques
+- Support multi-modal embedding (text, code, architectural diagrams)
+
+```python
+def semantic_context_retrieve(project_id, query_vector, top_k=5):
+    """Semantically retrieve most relevant context vectors"""
+    vector_db = VectorDatabase(project_id)
+    matching_contexts = vector_db.search(
+        query_vector,
+        similarity_threshold=0.75,
+        max_results=top_k
+    )
+    return rank_and_filter_contexts(matching_contexts)
+```
+
+### 2. Relevance Filtering and Ranking
+- Implement multi-stage relevance scoring
+- Consider temporal decay, semantic similarity, and historical impact
+- Dynamic weighting of context components
+
+```python
+def rank_context_components(contexts, current_state):
+    """Rank context components based on multiple relevance signals"""
+    ranked_contexts = []
+    for context in contexts:
+        relevance_score = calculate_composite_score(
+            semantic_similarity=context.semantic_score,
+            temporal_relevance=context.age_factor,
+            historical_impact=context.decision_weight
+        )
+        ranked_contexts.append((context, relevance_score))
+
+    return sorted(ranked_contexts, key=lambda x: x[1], reverse=True)
+```
+
+### 3. Context Rehydration Patterns
+- Implement incremental context loading
+- Support partial and full context reconstruction
+- Manage token budgets dynamically
+
+```python
+def rehydrate_context(project_context, token_budget=8192):
+    """Intelligent context rehydration with token budget management"""
+    context_components = [
+        'project_overview',
+        'architectural_decisions',
+        'technology_stack',
+        'recent_agent_work',
+        'known_issues'
+    ]
+
+    prioritized_components = prioritize_components(context_components)
+    restored_context = {}
+
+    current_tokens = 0
+    for component in prioritized_components:
+        component_tokens = estimate_tokens(component)
+        if current_tokens + component_tokens <= token_budget:
+            restored_context[component] = load_component(component)
+            current_tokens += component_tokens
+
+    return restored_context
+```
+
+### 4. Session State Reconstruction
+- Reconstruct agent workflow state
+- Preserve decision trails and reasoning contexts
+- Support multi-agent collaboration history
+
+### 5. Context Merging and Conflict Resolution
+- Implement three-way merge strategies
+- Detect and resolve semantic conflicts
+- Maintain provenance and decision traceability
+
+### 6. Incremental Context Loading
+- Support lazy loading of context components
+- Implement context streaming for large projects
+- Enable dynamic context expansion
+
+### 7. Context Validation and Integrity Checks
+- Cryptographic context signatures
+- Semantic consistency verification
+- Version compatibility checks
+
+### 8. Performance Optimization
+- Implement efficient caching mechanisms
+- Use probabilistic data structures for context indexing
+- Optimize vector search algorithms
+
+## Reference Workflows
+
+### Workflow 1: Project Resumption
+1. Retrieve most recent project context
+2. Validate context against current codebase
+3. Selectively restore relevant components
+4. Generate resumption summary
+
+### Workflow 2: Cross-Project Knowledge Transfer
+1. Extract semantic vectors from source project
+2. Map and transfer relevant knowledge
+3. Adapt context to target project's domain
+4. Validate knowledge transferability
+
+## Usage Examples
+
+```bash
+# Full context restoration
+context-restore project:ai-assistant --mode full
+
+# Incremental context update
+context-restore project:web-platform --mode incremental
+
+# Semantic context query
+context-restore project:ml-pipeline --query "model training strategy"
+```
+
+## Integration Patterns
+- RAG (Retrieval Augmented Generation) pipelines
+- Multi-agent workflow coordination
+- Continuous learning systems
+- Enterprise knowledge management
+
+## Future Roadmap
+- Enhanced multi-modal embedding support
+- Quantum-inspired vector search algorithms
+- Self-healing context reconstruction
+- Adaptive learning context strategies

commands/refactor-clean.md

@@ -0,0 +1,885 @@
+# Refactor and Clean Code
+
+You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its quality, maintainability, and performance.
+
+## Context
+The user needs help refactoring code to make it cleaner, more maintainable, and aligned with best practices. Focus on practical improvements that enhance code quality without over-engineering.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+### 1. Code Analysis
+First, analyze the current code for:
+- **Code Smells**
+  - Long methods/functions (>20 lines)
+  - Large classes (>200 lines)
+  - Duplicate code blocks
+  - Dead code and unused variables
+  - Complex conditionals and nested loops
+  - Magic numbers and hardcoded values
+  - Poor naming conventions
+  - Tight coupling between components
+  - Missing abstractions
+
+- **SOLID Violations**
+  - Single Responsibility Principle violations
+  - Open/Closed Principle issues
+  - Liskov Substitution problems
+  - Interface Segregation concerns
+  - Dependency Inversion violations
+
+- **Performance Issues**
+  - Inefficient algorithms (O(n²) or worse)
+  - Unnecessary object creation
+  - Memory leaks potential
+  - Blocking operations
+  - Missing caching opportunities
+
+### 2. Refactoring Strategy
+
+Create a prioritized refactoring plan:
+
+**Immediate Fixes (High Impact, Low Effort)**
+- Extract magic numbers to constants
+- Improve variable and function names
+- Remove dead code
+- Simplify boolean expressions
+- Extract duplicate code to functions
+
+**Method Extraction**
+```
+# Before
+def process_order(order):
+    # 50 lines of validation
+    # 30 lines of calculation
+    # 40 lines of notification
+
+# After
+def process_order(order):
+    validate_order(order)
+    total = calculate_order_total(order)
+    send_order_notifications(order, total)
+```
+
+**Class Decomposition**
+- Extract responsibilities to separate classes
+- Create interfaces for dependencies
+- Implement dependency injection
+- Use composition over inheritance
+
+**Pattern Application**
+- Factory pattern for object creation
+- Strategy pattern for algorithm variants
+- Observer pattern for event handling
+- Repository pattern for data access
+- Decorator pattern for extending behavior
+
+### 3. SOLID Principles in Action
+
+Provide concrete examples of applying each SOLID principle:
+
+**Single Responsibility Principle (SRP)**
+```python
+# BEFORE: Multiple responsibilities in one class
+class UserManager:
+    def create_user(self, data):
+        # Validate data
+        # Save to database
+        # Send welcome email
+        # Log activity
+        # Update cache
+        pass
+
+# AFTER: Each class has one responsibility
+class UserValidator:
+    def validate(self, data): pass
+
+class UserRepository:
+    def save(self, user): pass
+
+class EmailService:
+    def send_welcome_email(self, user): pass
+
+class UserActivityLogger:
+    def log_creation(self, user): pass
+
+class UserService:
+    def __init__(self, validator, repository, email_service, logger):
+        self.validator = validator
+        self.repository = repository
+        self.email_service = email_service
+        self.logger = logger
+
+    def create_user(self, data):
+        self.validator.validate(data)
+        user = self.repository.save(data)
+        self.email_service.send_welcome_email(user)
+        self.logger.log_creation(user)
+        return user
+```
+
+**Open/Closed Principle (OCP)**
+```python
+# BEFORE: Modification required for new discount types
+class DiscountCalculator:
+    def calculate(self, order, discount_type):
+        if discount_type == "percentage":
+            return order.total * 0.1
+        elif discount_type == "fixed":
+            return 10
+        elif discount_type == "tiered":
+            # More logic
+            pass
+
+# AFTER: Open for extension, closed for modification
+from abc import ABC, abstractmethod
+
+class DiscountStrategy(ABC):
+    @abstractmethod
+    def calculate(self, order): pass
+
+class PercentageDiscount(DiscountStrategy):
+    def __init__(self, percentage):
+        self.percentage = percentage
+
+    def calculate(self, order):
+        return order.total * self.percentage
+
+class FixedDiscount(DiscountStrategy):
+    def __init__(self, amount):
+        self.amount = amount
+
+    def calculate(self, order):
+        return self.amount
+
+class TieredDiscount(DiscountStrategy):
+    def calculate(self, order):
+        if order.total > 1000: return order.total * 0.15
+        if order.total > 500: return order.total * 0.10
+        return order.total * 0.05
+
+class DiscountCalculator:
+    def calculate(self, order, strategy: DiscountStrategy):
+        return strategy.calculate(order)
+```
+
+**Liskov Substitution Principle (LSP)**
+```typescript
+// BEFORE: Violates LSP - Square changes Rectangle behavior
+class Rectangle {
+    constructor(protected width: number, protected height: number) {}
+
+    setWidth(width: number) { this.width = width; }
+    setHeight(height: number) { this.height = height; }
+    area(): number { return this.width * this.height; }
+}
+
+class Square extends Rectangle {
+    setWidth(width: number) {
+        this.width = width;
+        this.height = width; // Breaks LSP
+    }
+    setHeight(height: number) {
+        this.width = height;
+        this.height = height; // Breaks LSP
+    }
+}
+
+// AFTER: Proper abstraction respects LSP
+interface Shape {
+    area(): number;
+}
+
+class Rectangle implements Shape {
+    constructor(private width: number, private height: number) {}
+    area(): number { return this.width * this.height; }
+}
+
+class Square implements Shape {
+    constructor(private side: number) {}
+    area(): number { return this.side * this.side; }
+}
+```
+
+**Interface Segregation Principle (ISP)**
+```java
+// BEFORE: Fat interface forces unnecessary implementations
+interface Worker {
+    void work();
+    void eat();
+    void sleep();
+}
+
+class Robot implements Worker {
+    public void work() { /* work */ }
+    public void eat() { /* robots don't eat! */ }
+    public void sleep() { /* robots don't sleep! */ }
+}
+
+// AFTER: Segregated interfaces
+interface Workable {
+    void work();
+}
+
+interface Eatable {
+    void eat();
+}
+
+interface Sleepable {
+    void sleep();
+}
+
+class Human implements Workable, Eatable, Sleepable {
+    public void work() { /* work */ }
+    public void eat() { /* eat */ }
+    public void sleep() { /* sleep */ }
+}
+
+class Robot implements Workable {
+    public void work() { /* work */ }
+}
+```
+
+**Dependency Inversion Principle (DIP)**
+```go
+// BEFORE: High-level module depends on low-level module
+type MySQLDatabase struct{}
+
+func (db *MySQLDatabase) Save(data string) {}
+
+type UserService struct {
+    db *MySQLDatabase // Tight coupling
+}
+
+func (s *UserService) CreateUser(name string) {
+    s.db.Save(name)
+}
+
+// AFTER: Both depend on abstraction
+type Database interface {
+    Save(data string)
+}
+
+type MySQLDatabase struct{}
+func (db *MySQLDatabase) Save(data string) {}
+
+type PostgresDatabase struct{}
+func (db *PostgresDatabase) Save(data string) {}
+
+type UserService struct {
+    db Database // Depends on abstraction
+}
+
+func NewUserService(db Database) *UserService {
+    return &UserService{db: db}
+}
+
+func (s *UserService) CreateUser(name string) {
+    s.db.Save(name)
+}
+```
+
+### 4. Complete Refactoring Scenarios
+
+**Scenario 1: Legacy Monolith to Clean Modular Architecture**
+
+```python
+# BEFORE: 500-line monolithic file
+class OrderSystem:
+    def process_order(self, order_data):
+        # Validation (100 lines)
+        if not order_data.get('customer_id'):
+            return {'error': 'No customer'}
+        if not order_data.get('items'):
+            return {'error': 'No items'}
+        # Database operations mixed in (150 lines)
+        conn = mysql.connector.connect(host='localhost', user='root')
+        cursor = conn.cursor()
+        cursor.execute("INSERT INTO orders...")
+        # Business logic (100 lines)
+        total = 0
+        for item in order_data['items']:
+            total += item['price'] * item['quantity']
+        # Email notifications (80 lines)
+        smtp = smtplib.SMTP('smtp.gmail.com')
+        smtp.sendmail(...)
+        # Logging and analytics (70 lines)
+        log_file = open('/var/log/orders.log', 'a')
+        log_file.write(f"Order processed: {order_data}")
+
+# AFTER: Clean, modular architecture
+# domain/entities.py
+from dataclasses import dataclass
+from typing import List
+from decimal import Decimal
+
+@dataclass
+class OrderItem:
+    product_id: str
+    quantity: int
+    price: Decimal
+
+@dataclass
+class Order:
+    customer_id: str
+    items: List[OrderItem]
+
+    @property
+    def total(self) -> Decimal:
+        return sum(item.price * item.quantity for item in self.items)
+
+# domain/repositories.py
+from abc import ABC, abstractmethod
+
+class OrderRepository(ABC):
+    @abstractmethod
+    def save(self, order: Order) -> str: pass
+
+    @abstractmethod
+    def find_by_id(self, order_id: str) -> Order: pass
+
+# infrastructure/mysql_order_repository.py
+class MySQLOrderRepository(OrderRepository):
+    def __init__(self, connection_pool):
+        self.pool = connection_pool
+
+    def save(self, order: Order) -> str:
+        with self.pool.get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "INSERT INTO orders (customer_id, total) VALUES (%s, %s)",
+                (order.customer_id, order.total)
+            )
+            return cursor.lastrowid
+
+# application/validators.py
+class OrderValidator:
+    def validate(self, order: Order) -> None:
+        if not order.customer_id:
+            raise ValueError("Customer ID is required")
+        if not order.items:
+            raise ValueError("Order must contain items")
+        if order.total <= 0:
+            raise ValueError("Order total must be positive")
+
+# application/services.py
+class OrderService:
+    def __init__(
+        self,
+        validator: OrderValidator,
+        repository: OrderRepository,
+        email_service: EmailService,
+        logger: Logger
+    ):
+        self.validator = validator
+        self.repository = repository
+        self.email_service = email_service
+        self.logger = logger
+
+    def process_order(self, order: Order) -> str:
+        self.validator.validate(order)
+        order_id = self.repository.save(order)
+        self.email_service.send_confirmation(order)
+        self.logger.info(f"Order {order_id} processed successfully")
+        return order_id
+```
+
+**Scenario 2: Code Smell Resolution Catalog**
+
+```typescript
+// SMELL: Long Parameter List
+// BEFORE
+function createUser(
+    firstName: string,
+    lastName: string,
+    email: string,
+    phone: string,
+    address: string,
+    city: string,
+    state: string,
+    zipCode: string
+) {}
+
+// AFTER: Parameter Object
+interface UserData {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    address: Address;
+}
+
+interface Address {
+    street: string;
+    city: string;
+    state: string;
+    zipCode: string;
+}
+
+function createUser(userData: UserData) {}
+
+// SMELL: Feature Envy (method uses another class's data more than its own)
+// BEFORE
+class Order {
+    calculateShipping(customer: Customer): number {
+        if (customer.isPremium) {
+            return customer.address.isInternational ? 0 : 5;
+        }
+        return customer.address.isInternational ? 20 : 10;
+    }
+}
+
+// AFTER: Move method to the class it envies
+class Customer {
+    calculateShippingCost(): number {
+        if (this.isPremium) {
+            return this.address.isInternational ? 0 : 5;
+        }
+        return this.address.isInternational ? 20 : 10;
+    }
+}
+
+class Order {
+    calculateShipping(customer: Customer): number {
+        return customer.calculateShippingCost();
+    }
+}
+
+// SMELL: Primitive Obsession
+// BEFORE
+function validateEmail(email: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+let userEmail: string = "test@example.com";
+
+// AFTER: Value Object
+class Email {
+    private readonly value: string;
+
+    constructor(email: string) {
+        if (!this.isValid(email)) {
+            throw new Error("Invalid email format");
+        }
+        this.value = email;
+    }
+
+    private isValid(email: string): boolean {
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+    }
+
+    toString(): string {
+        return this.value;
+    }
+}
+
+let userEmail = new Email("test@example.com"); // Validation automatic
+```
+
+### 5. Decision Frameworks
+
+**Code Quality Metrics Interpretation Matrix**
+
+| Metric | Good | Warning | Critical | Action |
+|--------|------|---------|----------|--------|
+| Cyclomatic Complexity | <10 | 10-15 | >15 | Split into smaller methods |
+| Method Lines | <20 | 20-50 | >50 | Extract methods, apply SRP |
+| Class Lines | <200 | 200-500 | >500 | Decompose into multiple classes |
+| Test Coverage | >80% | 60-80% | <60% | Add unit tests immediately |
+| Code Duplication | <3% | 3-5% | >5% | Extract common code |
+| Comment Ratio | 10-30% | <10% or >50% | N/A | Improve naming or reduce noise |
+| Dependency Count | <5 | 5-10 | >10 | Apply DIP, use facades |
+
+**Refactoring ROI Analysis**
+
+```
+Priority = (Business Value × Technical Debt) / (Effort × Risk)
+
+Business Value (1-10):
+- Critical path code: 10
+- Frequently changed: 8
+- User-facing features: 7
+- Internal tools: 5
+- Legacy unused: 2
+
+Technical Debt (1-10):
+- Causes production bugs: 10
+- Blocks new features: 8
+- Hard to test: 6
+- Style issues only: 2
+
+Effort (hours):
+- Rename variables: 1-2
+- Extract methods: 2-4
+- Refactor class: 4-8
+- Architecture change: 40+
+
+Risk (1-10):
+- No tests, high coupling: 10
+- Some tests, medium coupling: 5
+- Full tests, loose coupling: 2
+```
+
+**Technical Debt Prioritization Decision Tree**
+
+```
+Is it causing production bugs?
+├─ YES → Priority: CRITICAL (Fix immediately)
+└─ NO → Is it blocking new features?
+    ├─ YES → Priority: HIGH (Schedule this sprint)
+    └─ NO → Is it frequently modified?
+        ├─ YES → Priority: MEDIUM (Next quarter)
+        └─ NO → Is code coverage < 60%?
+            ├─ YES → Priority: MEDIUM (Add tests)
+            └─ NO → Priority: LOW (Backlog)
+```
+
+### 6. Modern Code Quality Practices (2024-2025)
+
+**AI-Assisted Code Review Integration**
+
+```yaml
+# .github/workflows/ai-review.yml
+name: AI Code Review
+on: [pull_request]
+
+jobs:
+  ai-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # GitHub Copilot Autofix
+      - uses: github/copilot-autofix@v1
+        with:
+          languages: 'python,typescript,go'
+
+      # CodeRabbit AI Review
+      - uses: coderabbitai/action@v1
+        with:
+          review_type: 'comprehensive'
+          focus: 'security,performance,maintainability'
+
+      # Codium AI PR-Agent
+      - uses: codiumai/pr-agent@v1
+        with:
+          commands: '/review --pr_reviewer.num_code_suggestions=5'
+```
+
+**Static Analysis Toolchain**
+
+```python
+# pyproject.toml
+[tool.ruff]
+line-length = 100
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "C90", # mccabe complexity
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "A",   # flake8-builtins
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+    "RET", # flake8-return
+]
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+warn_unused_ignores = true
+
+[tool.coverage]
+fail_under = 80
+```
+
+```javascript
+// .eslintrc.json
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended-type-checked",
+    "plugin:sonarjs/recommended",
+    "plugin:security/recommended"
+  ],
+  "plugins": ["sonarjs", "security", "no-loops"],
+  "rules": {
+    "complexity": ["error", 10],
+    "max-lines-per-function": ["error", 20],
+    "max-params": ["error", 3],
+    "no-loops/no-loops": "warn",
+    "sonarjs/cognitive-complexity": ["error", 15]
+  }
+}
+```
+
+**Automated Refactoring Suggestions**
+
+```python
+# Use Sourcery for automatic refactoring suggestions
+# sourcery.yaml
+rules:
+  - id: convert-to-list-comprehension
+  - id: merge-duplicate-blocks
+  - id: use-named-expression
+  - id: inline-immediately-returned-variable
+
+# Example: Sourcery will suggest
+# BEFORE
+result = []
+for item in items:
+    if item.is_active:
+        result.append(item.name)
+
+# AFTER (auto-suggested)
+result = [item.name for item in items if item.is_active]
+```
+
+**Code Quality Dashboard Configuration**
+
+```yaml
+# sonar-project.properties
+sonar.projectKey=my-project
+sonar.sources=src
+sonar.tests=tests
+sonar.coverage.exclusions=**/*_test.py,**/test_*.py
+sonar.python.coverage.reportPaths=coverage.xml
+
+# Quality Gates
+sonar.qualitygate.wait=true
+sonar.qualitygate.timeout=300
+
+# Thresholds
+sonar.coverage.threshold=80
+sonar.duplications.threshold=3
+sonar.maintainability.rating=A
+sonar.reliability.rating=A
+sonar.security.rating=A
+```
+
+**Security-Focused Refactoring**
+
+```python
+# Use Semgrep for security-aware refactoring
+# .semgrep.yml
+rules:
+  - id: sql-injection-risk
+    pattern: execute($QUERY)
+    message: Potential SQL injection
+    severity: ERROR
+    fix: Use parameterized queries
+
+  - id: hardcoded-secrets
+    pattern: password = "..."
+    message: Hardcoded password detected
+    severity: ERROR
+    fix: Use environment variables or secret manager
+
+# CodeQL security analysis
+# .github/workflows/codeql.yml
+- uses: github/codeql-action/analyze@v3
+  with:
+    category: "/language:python"
+    queries: security-extended,security-and-quality
+```
+
+### 7. Refactored Implementation
+
+Provide the complete refactored code with:
+
+**Clean Code Principles**
+- Meaningful names (searchable, pronounceable, no abbreviations)
+- Functions do one thing well
+- No side effects
+- Consistent abstraction levels
+- DRY (Don't Repeat Yourself)
+- YAGNI (You Aren't Gonna Need It)
+
+**Error Handling**
+```python
+# Use specific exceptions
+class OrderValidationError(Exception):
+    pass
+
+class InsufficientInventoryError(Exception):
+    pass
+
+# Fail fast with clear messages
+def validate_order(order):
+    if not order.items:
+        raise OrderValidationError("Order must contain at least one item")
+
+    for item in order.items:
+        if item.quantity <= 0:
+            raise OrderValidationError(f"Invalid quantity for {item.name}")
+```
+
+**Documentation**
+```python
+def calculate_discount(order: Order, customer: Customer) -> Decimal:
+    """
+    Calculate the total discount for an order based on customer tier and order value.
+
+    Args:
+        order: The order to calculate discount for
+        customer: The customer making the order
+
+    Returns:
+        The discount amount as a Decimal
+
+    Raises:
+        ValueError: If order total is negative
+    """
+```
+
+### 8. Testing Strategy
+
+Generate comprehensive tests for the refactored code:
+
+**Unit Tests**
+```python
+class TestOrderProcessor:
+    def test_validate_order_empty_items(self):
+        order = Order(items=[])
+        with pytest.raises(OrderValidationError):
+            validate_order(order)
+
+    def test_calculate_discount_vip_customer(self):
+        order = create_test_order(total=1000)
+        customer = Customer(tier="VIP")
+        discount = calculate_discount(order, customer)
+        assert discount == Decimal("100.00")  # 10% VIP discount
+```
+
+**Test Coverage**
+- All public methods tested
+- Edge cases covered
+- Error conditions verified
+- Performance benchmarks included
+
+### 9. Before/After Comparison
+
+Provide clear comparisons showing improvements:
+
+**Metrics**
+- Cyclomatic complexity reduction
+- Lines of code per method
+- Test coverage increase
+- Performance improvements
+
+**Example**
+```
+Before:
+- processData(): 150 lines, complexity: 25
+- 0% test coverage
+- 3 responsibilities mixed
+
+After:
+- validateInput(): 20 lines, complexity: 4
+- transformData(): 25 lines, complexity: 5
+- saveResults(): 15 lines, complexity: 3
+- 95% test coverage
+- Clear separation of concerns
+```
+
+### 10. Migration Guide
+
+If breaking changes are introduced:
+
+**Step-by-Step Migration**
+1. Install new dependencies
+2. Update import statements
+3. Replace deprecated methods
+4. Run migration scripts
+5. Execute test suite
+
+**Backward Compatibility**
+```python
+# Temporary adapter for smooth migration
+class LegacyOrderProcessor:
+    def __init__(self):
+        self.processor = OrderProcessor()
+
+    def process(self, order_data):
+        # Convert legacy format
+        order = Order.from_legacy(order_data)
+        return self.processor.process(order)
+```
+
+### 11. Performance Optimizations
+
+Include specific optimizations:
+
+**Algorithm Improvements**
+```python
+# Before: O(n²)
+for item in items:
+    for other in items:
+        if item.id == other.id:
+            # process
+
+# After: O(n)
+item_map = {item.id: item for item in items}
+for item_id, item in item_map.items():
+    # process
+```
+
+**Caching Strategy**
+```python
+from functools import lru_cache
+
+@lru_cache(maxsize=128)
+def calculate_expensive_metric(data_id: str) -> float:
+    # Expensive calculation cached
+    return result
+```
+
+### 12. Code Quality Checklist
+
+Ensure the refactored code meets these criteria:
+
+- [ ] All methods < 20 lines
+- [ ] All classes < 200 lines
+- [ ] No method has > 3 parameters
+- [ ] Cyclomatic complexity < 10
+- [ ] No nested loops > 2 levels
+- [ ] All names are descriptive
+- [ ] No commented-out code
+- [ ] Consistent formatting
+- [ ] Type hints added (Python/TypeScript)
+- [ ] Error handling comprehensive
+- [ ] Logging added for debugging
+- [ ] Performance metrics included
+- [ ] Documentation complete
+- [ ] Tests achieve > 80% coverage
+- [ ] No security vulnerabilities
+- [ ] AI code review passed
+- [ ] Static analysis clean (SonarQube/CodeQL)
+- [ ] No hardcoded secrets
+
+## Severity Levels
+
+Rate issues found and improvements made:
+
+**Critical**: Security vulnerabilities, data corruption risks, memory leaks
+**High**: Performance bottlenecks, maintainability blockers, missing tests
+**Medium**: Code smells, minor performance issues, incomplete documentation
+**Low**: Style inconsistencies, minor naming issues, nice-to-have features
+
+## Output Format
+
+1. **Analysis Summary**: Key issues found and their impact
+2. **Refactoring Plan**: Prioritized list of changes with effort estimates
+3. **Refactored Code**: Complete implementation with inline comments explaining changes
+4. **Test Suite**: Comprehensive tests for all refactored components
+5. **Migration Guide**: Step-by-step instructions for adopting changes
+6. **Metrics Report**: Before/after comparison of code quality metrics
+7. **AI Review Results**: Summary of automated code review findings
+8. **Quality Dashboard**: Link to SonarQube/CodeQL results
+
+Focus on delivering practical, incremental improvements that can be adopted immediately while maintaining system stability.

commands/tech-debt.md

@@ -0,0 +1,371 @@
+# Technical Debt Analysis and Remediation
+
+You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create actionable remediation plans.
+
+## Context
+The user needs a comprehensive technical debt analysis to understand what's slowing down development, increasing bugs, and creating maintenance challenges. Focus on practical, measurable improvements with clear ROI.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+### 1. Technical Debt Inventory
+
+Conduct a thorough scan for all types of technical debt:
+
+**Code Debt**
+- **Duplicated Code**
+  - Exact duplicates (copy-paste)
+  - Similar logic patterns
+  - Repeated business rules
+  - Quantify: Lines duplicated, locations
+  
+- **Complex Code**
+  - High cyclomatic complexity (>10)
+  - Deeply nested conditionals (>3 levels)
+  - Long methods (>50 lines)
+  - God classes (>500 lines, >20 methods)
+  - Quantify: Complexity scores, hotspots
+
+- **Poor Structure**
+  - Circular dependencies
+  - Inappropriate intimacy between classes
+  - Feature envy (methods using other class data)
+  - Shotgun surgery patterns
+  - Quantify: Coupling metrics, change frequency
+
+**Architecture Debt**
+- **Design Flaws**
+  - Missing abstractions
+  - Leaky abstractions
+  - Violated architectural boundaries
+  - Monolithic components
+  - Quantify: Component size, dependency violations
+
+- **Technology Debt**
+  - Outdated frameworks/libraries
+  - Deprecated API usage
+  - Legacy patterns (e.g., callbacks vs promises)
+  - Unsupported dependencies
+  - Quantify: Version lag, security vulnerabilities
+
+**Testing Debt**
+- **Coverage Gaps**
+  - Untested code paths
+  - Missing edge cases
+  - No integration tests
+  - Lack of performance tests
+  - Quantify: Coverage %, critical paths untested
+
+- **Test Quality**
+  - Brittle tests (environment-dependent)
+  - Slow test suites
+  - Flaky tests
+  - No test documentation
+  - Quantify: Test runtime, failure rate
+
+**Documentation Debt**
+- **Missing Documentation**
+  - No API documentation
+  - Undocumented complex logic
+  - Missing architecture diagrams
+  - No onboarding guides
+  - Quantify: Undocumented public APIs
+
+**Infrastructure Debt**
+- **Deployment Issues**
+  - Manual deployment steps
+  - No rollback procedures
+  - Missing monitoring
+  - No performance baselines
+  - Quantify: Deployment time, failure rate
+
+### 2. Impact Assessment
+
+Calculate the real cost of each debt item:
+
+**Development Velocity Impact**
+```
+Debt Item: Duplicate user validation logic
+Locations: 5 files
+Time Impact: 
+- 2 hours per bug fix (must fix in 5 places)
+- 4 hours per feature change
+- Monthly impact: ~20 hours
+Annual Cost: 240 hours × $150/hour = $36,000
+```
+
+**Quality Impact**
+```
+Debt Item: No integration tests for payment flow
+Bug Rate: 3 production bugs/month
+Average Bug Cost:
+- Investigation: 4 hours
+- Fix: 2 hours  
+- Testing: 2 hours
+- Deployment: 1 hour
+Monthly Cost: 3 bugs × 9 hours × $150 = $4,050
+Annual Cost: $48,600
+```
+
+**Risk Assessment**
+- **Critical**: Security vulnerabilities, data loss risk
+- **High**: Performance degradation, frequent outages
+- **Medium**: Developer frustration, slow feature delivery
+- **Low**: Code style issues, minor inefficiencies
+
+### 3. Debt Metrics Dashboard
+
+Create measurable KPIs:
+
+**Code Quality Metrics**
+```yaml
+Metrics:
+  cyclomatic_complexity:
+    current: 15.2
+    target: 10.0
+    files_above_threshold: 45
+    
+  code_duplication:
+    percentage: 23%
+    target: 5%
+    duplication_hotspots:
+      - src/validation: 850 lines
+      - src/api/handlers: 620 lines
+      
+  test_coverage:
+    unit: 45%
+    integration: 12%
+    e2e: 5%
+    target: 80% / 60% / 30%
+    
+  dependency_health:
+    outdated_major: 12
+    outdated_minor: 34
+    security_vulnerabilities: 7
+    deprecated_apis: 15
+```
+
+**Trend Analysis**
+```python
+debt_trends = {
+    "2024_Q1": {"score": 750, "items": 125},
+    "2024_Q2": {"score": 820, "items": 142},
+    "2024_Q3": {"score": 890, "items": 156},
+    "growth_rate": "18% quarterly",
+    "projection": "1200 by 2025_Q1 without intervention"
+}
+```
+
+### 4. Prioritized Remediation Plan
+
+Create an actionable roadmap based on ROI:
+
+**Quick Wins (High Value, Low Effort)**
+Week 1-2:
+```
+1. Extract duplicate validation logic to shared module
+   Effort: 8 hours
+   Savings: 20 hours/month
+   ROI: 250% in first month
+
+2. Add error monitoring to payment service
+   Effort: 4 hours
+   Savings: 15 hours/month debugging
+   ROI: 375% in first month
+
+3. Automate deployment script
+   Effort: 12 hours
+   Savings: 2 hours/deployment × 20 deploys/month
+   ROI: 333% in first month
+```
+
+**Medium-Term Improvements (Month 1-3)**
+```
+1. Refactor OrderService (God class)
+   - Split into 4 focused services
+   - Add comprehensive tests
+   - Create clear interfaces
+   Effort: 60 hours
+   Savings: 30 hours/month maintenance
+   ROI: Positive after 2 months
+
+2. Upgrade React 16 → 18
+   - Update component patterns
+   - Migrate to hooks
+   - Fix breaking changes
+   Effort: 80 hours  
+   Benefits: Performance +30%, Better DX
+   ROI: Positive after 3 months
+```
+
+**Long-Term Initiatives (Quarter 2-4)**
+```
+1. Implement Domain-Driven Design
+   - Define bounded contexts
+   - Create domain models
+   - Establish clear boundaries
+   Effort: 200 hours
+   Benefits: 50% reduction in coupling
+   ROI: Positive after 6 months
+
+2. Comprehensive Test Suite
+   - Unit: 80% coverage
+   - Integration: 60% coverage
+   - E2E: Critical paths
+   Effort: 300 hours
+   Benefits: 70% reduction in bugs
+   ROI: Positive after 4 months
+```
+
+### 5. Implementation Strategy
+
+**Incremental Refactoring**
+```python
+# Phase 1: Add facade over legacy code
+class PaymentFacade:
+    def __init__(self):
+        self.legacy_processor = LegacyPaymentProcessor()
+    
+    def process_payment(self, order):
+        # New clean interface
+        return self.legacy_processor.doPayment(order.to_legacy())
+
+# Phase 2: Implement new service alongside
+class PaymentService:
+    def process_payment(self, order):
+        # Clean implementation
+        pass
+
+# Phase 3: Gradual migration
+class PaymentFacade:
+    def __init__(self):
+        self.new_service = PaymentService()
+        self.legacy = LegacyPaymentProcessor()
+        
+    def process_payment(self, order):
+        if feature_flag("use_new_payment"):
+            return self.new_service.process_payment(order)
+        return self.legacy.doPayment(order.to_legacy())
+```
+
+**Team Allocation**
+```yaml
+Debt_Reduction_Team:
+  dedicated_time: "20% sprint capacity"
+  
+  roles:
+    - tech_lead: "Architecture decisions"
+    - senior_dev: "Complex refactoring"  
+    - dev: "Testing and documentation"
+    
+  sprint_goals:
+    - sprint_1: "Quick wins completed"
+    - sprint_2: "God class refactoring started"
+    - sprint_3: "Test coverage >60%"
+```
+
+### 6. Prevention Strategy
+
+Implement gates to prevent new debt:
+
+**Automated Quality Gates**
+```yaml
+pre_commit_hooks:
+  - complexity_check: "max 10"
+  - duplication_check: "max 5%"
+  - test_coverage: "min 80% for new code"
+  
+ci_pipeline:
+  - dependency_audit: "no high vulnerabilities"
+  - performance_test: "no regression >10%"
+  - architecture_check: "no new violations"
+  
+code_review:
+  - requires_two_approvals: true
+  - must_include_tests: true
+  - documentation_required: true
+```
+
+**Debt Budget**
+```python
+debt_budget = {
+    "allowed_monthly_increase": "2%",
+    "mandatory_reduction": "5% per quarter",
+    "tracking": {
+        "complexity": "sonarqube",
+        "dependencies": "dependabot",
+        "coverage": "codecov"
+    }
+}
+```
+
+### 7. Communication Plan
+
+**Stakeholder Reports**
+```markdown
+## Executive Summary
+- Current debt score: 890 (High)
+- Monthly velocity loss: 35%
+- Bug rate increase: 45%
+- Recommended investment: 500 hours
+- Expected ROI: 280% over 12 months
+
+## Key Risks
+1. Payment system: 3 critical vulnerabilities
+2. Data layer: No backup strategy
+3. API: Rate limiting not implemented
+
+## Proposed Actions
+1. Immediate: Security patches (this week)
+2. Short-term: Core refactoring (1 month)
+3. Long-term: Architecture modernization (6 months)
+```
+
+**Developer Documentation**
+```markdown
+## Refactoring Guide
+1. Always maintain backward compatibility
+2. Write tests before refactoring
+3. Use feature flags for gradual rollout
+4. Document architectural decisions
+5. Measure impact with metrics
+
+## Code Standards
+- Complexity limit: 10
+- Method length: 20 lines
+- Class length: 200 lines
+- Test coverage: 80%
+- Documentation: All public APIs
+```
+
+### 8. Success Metrics
+
+Track progress with clear KPIs:
+
+**Monthly Metrics**
+- Debt score reduction: Target -5%
+- New bug rate: Target -20%
+- Deployment frequency: Target +50%
+- Lead time: Target -30%
+- Test coverage: Target +10%
+
+**Quarterly Reviews**
+- Architecture health score
+- Developer satisfaction survey
+- Performance benchmarks
+- Security audit results
+- Cost savings achieved
+
+## Output Format
+
+1. **Debt Inventory**: Comprehensive list categorized by type with metrics
+2. **Impact Analysis**: Cost calculations and risk assessments
+3. **Prioritized Roadmap**: Quarter-by-quarter plan with clear deliverables
+4. **Quick Wins**: Immediate actions for this sprint
+5. **Implementation Guide**: Step-by-step refactoring strategies
+6. **Prevention Plan**: Processes to avoid accumulating new debt
+7. **ROI Projections**: Expected returns on debt reduction investment
+
+Focus on delivering measurable improvements that directly impact development velocity, system reliability, and team morale.