bug-investigator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Role
Debug Agent

# Trigger
- User invokes DEBUG workflow.
- Router routes DEBUG intent to bug-investigator.

# Description
The Bug-Investigator skill provides systematic debugging capabilities following the LOG FIRST approach. It gathers evidence, identifies root causes, and creates reproduction steps before any fix is attempted.

# Agent Capabilities
- **Evidence Collection:** Gather logs, errors, stack traces systematically
- **Root Cause Analysis:** Identify underlying causes using evidence
- **Reproduction Steps:** Create minimal steps to reproduce the issue
- **Regression Test Guidance:** Help write tests that prevent future occurrences
- **Variant Coverage:** Ensure edge cases and non-default scenarios are considered

# Inputs
- User description of the issue
- Logs, error messages, stack traces
- Existing memory (patterns.md for similar issues)
- Git context (recent changes)
- Code files related to the issue

# Outputs
- Evidence summary
- Root cause hypothesis
- Reproduction steps
- Regression test requirements
- Router contract (YAML)

# Steps

## 1. LOAD Memory
Read `.opencode/context/01_memory/patterns.md` for similar issues.
```
patterns = load_memory_file("patterns.md")
similar_issues = find_similar_issues(patterns, issue_description)
```

## 2. Gather Evidence
Collect all available evidence systematically:
- Error messages and exceptions
- Stack traces (full traceback)
- Log files and outputs
- User reproduction steps
- Git history (recent changes)
- Test failures

**Evidence Collection Checklist:**
- [ ] Error messages captured verbatim
- [ ] Full stack trace recorded
- [ ] Log files examined
- [ ] User steps documented
- [ ] Git blame checked for recent changes
- [ ] Related tests reviewed

## 3. Analyze Evidence
Group evidence by category:
- **Environment:** OS, version, configuration
- **Code:** Stack trace, line numbers, function calls
- **Data:** Input values, state at failure
- **Timing:** When failure occurred, sequence of events

Look for patterns:
- Repeated errors
- Common code paths
- Environmental factors
- Recent changes that may have introduced the issue

## 4. Formulate Root Cause Hypothesis
Create hypothesis based on evidence (NOT speculation):
```
Root Cause: [Specific cause]
Evidence: [List of supporting evidence]
Confidence: [HIGH/MEDIUM/LOW]
```

**Criteria for Root Cause:**
- Must be supported by evidence
- Must explain all symptoms
- Must be actionable (can be fixed)

## 5. Create Reproduction Steps
Write minimal steps to reproduce the issue:
```
1. [Step 1]
2. [Step 2]
...
N. [Observe failure]
```

**Reproduction Requirements:**
- Minimal (no extra steps)
- Reproducible (works consistently)
- Verifiable (can confirm fix)

## 6. Define Regression Test Requirements
Specify what tests should prevent this issue:
- Test type (unit, integration, e2e)
- Input scenarios
- Expected behavior

## 7. Output Contract
Generate YAML contract with investigation results.

# Output Contract Template
```yaml
router_contract:
  status: COMPLETE
  workflow: DEBUG
  phase: INVESTIGATION
  evidence_collected:
    - "Error: Connection refused in auth.py:42"
    - "Stack trace: TimeoutException at network.py:100"
  root_cause: "Network timeout due to missing retry logic"
  confidence: HIGH
  reproduction_steps:
    - "1. Start the server"

From lshtram/nso, MIT.

More from lshtram/nso