Technical Design: troubleshoot-enhancement

Technical Design: troubleshoot-enhancement

Metadata

• Feature: troubleshoot-enhancement
• Status: DRAFT
• Created: 2026-01-30

1. Overview

1.1 Summary

Enhance the ZERG troubleshoot system from basic regex error parsing to a world-class diagnostic engine with multi-language error intelligence, cross-worker log correlation, Bayesian hypothesis ranking, code-aware recovery planning, deep environment diagnostics, and interactive resolution workflows.

1.2 Goals

• Make /zerg:troubleshoot the most comprehensive code debugging tool available
• Provide actionable, evidence-backed root cause analysis
• Automate the entire diagnostic workflow from symptom to resolution

1.3 Non-Goals

• AI/LLM-powered analysis (this is deterministic code analysis)
• Real-time monitoring (this is post-hoc diagnosis)
• Support for non-text-based errors (binary/image)

2. Architecture

2.1 High-Level Design

┌─────────────────────────────────────────────────────────────────┐
│                    TroubleshootCommand (enhanced)                │
│  ┌───────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐  │
│  │ ErrorIntel │ │ LogCorrelator│ │ Hypothesis │ │ Recovery   │  │
│  │ Engine     │ │              │ │ Engine     │ │ Planner    │  │
│  └─────┬─────┘ └──────┬───────┘ └─────┬──────┘ └─────┬──────┘  │
│        │               │               │              │         │
│  ┌─────┴─────┐ ┌──────┴───────┐ ┌─────┴──────┐ ┌────┴───────┐ │
│  │ MultiLang │ │  Timeline    │ │  Bayesian  │ │ CodeAware  │ │
│  │ Parser    │ │  Builder     │ │  Scorer    │ │ Fixer      │ │
│  └─────┬─────┘ └──────┬───────┘ └─────┬──────┘ └─────┬──────┘ │
│        │               │               │              │         │
│  ┌─────┴─────┐ ┌──────┴───────┐ ┌─────┴──────┐ ┌────┴───────┐ │
│  │ ErrorChain│ │  CrossWorker │ │  Knowledge │ │ DependGraph│ │
│  │ Analyzer  │ │  Correlator  │ │  Base      │ │ Analyzer   │ │
│  └───────────┘ └──────────────┘ └────────────┘ └────────────┘  │
│                                                                  │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐  │
│  │ EnvDiag     │ │ Interactive  │ │ ReportGenerator          │  │
│  │ (enhanced)  │ │ Wizard       │ │ (md/json/html)           │  │
│  └─────────────┘ └──────────────┘ └──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

2.2 Component Breakdown

2.3 Data Flow

1. User invokes zerg troubleshoot with error/feature/flags
2. ErrorIntelEngine parses and classifies the error across languages
3. LogCorrelator builds timeline and finds cross-worker patterns
4. HypothesisEngine generates ranked hypotheses with evidence
5. HypothesisEngine auto-tests hypotheses and updates confidence
6. CodeAwareFixer generates recovery plan with dependency awareness
7. EnvDiagnostics checks environment health
8. ReportGenerator produces structured output
9. InteractiveWizard guides user through resolution (if --interactive)

3. Detailed Design

3.1 Data Models (types.py)

class ErrorSeverity(Enum):
    CRITICAL = "critical"   # System down, data loss
    ERROR = "error"         # Feature broken
    WARNING = "warning"     # Degraded functionality
    INFO = "info"           # Informational

class ErrorCategory(Enum):
    WORKER_FAILURE = "worker_failure"
    TASK_FAILURE = "task_failure"
    STATE_CORRUPTION = "state_corruption"
    INFRASTRUCTURE = "infrastructure"
    CODE_ERROR = "code_error"
    DEPENDENCY = "dependency"
    MERGE_CONFLICT = "merge_conflict"
    ENVIRONMENT = "environment"
    CONFIGURATION = "configuration"
    UNKNOWN = "unknown"

@dataclass
class ErrorFingerprint:
    hash: str               # Dedupe key
    language: str            # python, javascript, go, rust, java, cpp
    error_type: str
    message_template: str    # Parameterized message
    file: str
    line: int
    column: int
    function: str
    module: str
    chain: list[ErrorFingerprint]  # caused-by chain

@dataclass
class TimelineEvent:
    timestamp: str
    worker_id: int
    event_type: str          # error, warning, info, state_change
    message: str
    source_file: str
    line_number: int
    correlation_id: str      # For grouping related events

@dataclass
class Evidence:
    description: str
    source: str              # log, state, git, system, code
    confidence: float        # 0.0 - 1.0
    data: dict[str, Any]

@dataclass
class ScoredHypothesis:
    description: str
    category: ErrorCategory
    prior_probability: float
    evidence_for: list[Evidence]
    evidence_against: list[Evidence]
    posterior_probability: float  # After evidence
    test_command: str
    test_result: str | None      # None = untested
    suggested_fix: str

4. Key Decisions

Decision: Bayesian Hypothesis Scoring

Context: Current system uses simple high/medium/low likelihood strings.

Options:

1. Simple weighted scoring
2. Bayesian probability updates
3. ML-based classification

Decision: Bayesian probability updates

Rationale: Provides principled evidence integration, interpretable confidence scores, and doesn't require training data. Simple enough to implement in pure Python.

Decision: New modules vs. refactoring existing

Context: Existing diagnostics/ has 4 modules. Enhancement is substantial.

Options:

1. Refactor existing modules in-place
2. Create new modules alongside existing
3. Replace existing entirely

Decision: Create new modules alongside existing, then update TroubleshootCommand to use them. Existing modules continue working, new modules add capabilities.

Rationale: Zero-risk migration path. Old tests keep passing. New functionality is additive.

5. Implementation Plan

Phase Summary

File Ownership

Dependency Graph

L1: TE-L1-001 (types) ──┐
    TE-L1-002 (kb)    ──┤
                         │
L2: TE-L2-001 (error)  ─┤─ depends on L1
    TE-L2-002 (logs)   ─┤
    TE-L2-003 (hypo)   ─┤
    TE-L2-004 (fixer)  ─┤
    TE-L2-005 (env)    ─┘
                         │
L3: TE-L3-001 (cmd)   ──┤─ depends on L2
    TE-L3-002 (init)   ─┘
                         │
L4: TE-L4-001..005     ──┤─ depends on L3
                         │
L5: TE-L5-001 (docs)  ──┘─ depends on L4

6. Risk Assessment

7. Parallel Execution Notes

Recommended Workers

• Minimum: 2 workers
• Optimal: 5 workers (widest level is L2 with 5 tasks)
• Maximum: 5 workers

Estimated Duration

• Single worker: ~15 tasks sequential
• With 5 workers: 5 levels of parallelized work

8. Approval