1545 Requirements 7deaa141

# Requirements: Troubleshoot Enhancement

**Feature**: troubleshoot-enhancement
**Status**: APPROVED
**Created**: 2026-01-30

## Goal

Transform `/zerg:troubleshoot` into a world-class software code troubleshooter with:
- Deep multi-language error analysis with semantic understanding
- Automated log correlation across workers with timeline reconstruction
- Hypothesis testing with executable verification commands
- Intelligent fix suggestions with code-aware recovery
- Environment diagnostics with dependency graph analysis
- Structured resolution workflows with confidence scoring

## Functional Requirements

### FR-1: Advanced Error Intelligence
- Multi-language AST-aware error parsing (Python, JS/TS, Go, Rust, Java, C++)
- Stack trace decompilation with source mapping
- Error fingerprinting for deduplication across workers
- Semantic error classification beyond regex matching
- Error chain analysis (caused-by traversal)

### FR-2: Log Correlation Engine
- Timeline reconstruction across all worker logs
- Temporal clustering of related errors
- Cross-worker error correlation with causality inference
- Log pattern evolution tracking (same error changing over time)
- Structured log parsing (JSONL + plaintext)

### FR-3: Hypothesis Engine
- Evidence-weighted hypothesis ranking (Bayesian-style scoring)
- Automated hypothesis testing with executable commands
- Hypothesis chaining (if A confirmed, test B)
- Confidence scoring with evidence tracking
- Knowledge base of common ZERG failure patterns

### FR-4: Code-Aware Recovery
- Context-aware fix suggestions based on error location
- Dependency graph analysis for import/module errors
- Git-aware recovery (blame, diff, bisect suggestions)
- Safe vs destructive action classification with rollback plans
- Multi-step recovery orchestration with verification gates

### FR-5: Environment Diagnostics
- Python environment introspection (venv, packages, versions)
- Docker health and resource analysis
- Network connectivity verification
- Resource utilization (CPU, memory, disk, file descriptors)
- Configuration validation against expected state

### FR-6: Interactive Resolution Workflow
- Guided troubleshooting wizard mode (`--interactive`)
- Progressive disclosure (summary → detail → deep dive)
- Session persistence for multi-step investigations
- Report generation (markdown, JSON, HTML)
- Integration with `/zerg:retry` for seamless recovery

## Non-Functional Requirements

- All new modules must have ≥90% test coverage
- No new external dependencies beyond stdlib + existing deps (click, rich)
- Backward-compatible with existing `zerg troubleshoot` CLI interface
- Each diagnostic phase must complete within 30 seconds