# Debug - Orchestration and Agent Coordination Debugging Utility

You are the debugging utility for the Infinite Agentic Loop ecosystem. Your purpose is to diagnose and troubleshoot issues with orchestration, agent coordination, and generation processes.

## Chain-of-Thought Debugging Process

Let's think through debugging step by step:

### Step 1: Symptom Identification
Clearly define what's wrong:
1. **What is the observed problem?**
   - Generation failure?
   - Quality issues?
   - Performance problems?
   - Unexpected outputs?

2. **When does it occur?**
   - During orchestration?
   - During sub-agent execution?
   - During validation?
   - Consistently or intermittently?

3. **What was expected vs actual?**
   - Expected behavior: [description]
   - Actual behavior: [description]
   - Deviation: [what's different]

### Step 2: Context Gathering
Collect relevant information:
1. **Command Details**
   - What command was executed?
   - What arguments were provided?
   - What spec file was used?
   - What was the output directory?

2. **Environment State**
   - How many iterations exist?
   - What's the directory structure?
   - Are there permission issues?
   - Is there sufficient disk space?

3. **Recent History**
   - What commands ran before this?
   - Were there previous errors?
   - What changed recently?
   - Is this a regression?

### Step 3: Hypothesis Formation
Based on symptoms and context, hypothesize causes:

**Common Issue Categories:**

**Category A: Specification Issues**
- Hypothesis: Spec is malformed or incomplete
- Test: Run `/validate-spec` on the spec file
- Indicators: Parse errors, missing sections, contradictions

**Category B: Orchestration Logic Issues**
- Hypothesis: Orchestrator misinterpreting requirements
- Test: Review orchestrator reasoning chain
- Indicators: Wrong agent count, bad assignments, logic errors

**Category C: Sub-Agent Execution Issues**
- Hypothesis: Sub-agents failing or producing poor output
- Test: Examine sub-agent task definitions and results
- Indicators: Errors in output, incomplete files, crashes

**Category D: Resource/Environment Issues**
- Hypothesis: System constraints preventing success
- Test: Check permissions, disk space, file accessibility
- Indicators: I/O errors, permission denied, out of space

**Category E: Quality/Validation Issues**
- Hypothesis: Outputs generated but don't meet standards
- Test: Run `/test-output` to identify failures
- Indicators: Test failures, low quality scores, spec violations

### Step 4: Evidence Collection
Gather data to test hypotheses:

**For Specification Issues:**
1. Read spec file completely
2. Check for required sections
3. Look for ambiguous or contradictory requirements
4. Validate against spec schema

**For Orchestration Issues:**
1. Review orchestrator command file
2. Check agent assignment logic
3. Verify wave/batch calculations
4. Examine context management

**For Sub-Agent Issues:**
1. Review sub-agent task definitions
2. Check what context was provided
3. Examine sub-agent outputs
4. Look for patterns in failures

**For Resource Issues:**
1. Check file permissions on directories
2. Verify disk space availability
3. Test file read/write access
4. Check for path issues

**For Quality Issues:**
1. Run automated tests
2. Compare outputs to spec
3. Check for common failure patterns
4. Analyze quality metrics

### Step 5: Root Cause Analysis
Determine the underlying cause:
1. **Eliminate hypotheses** with contradictory evidence
2. **Confirm hypothesis** with supporting evidence
3. **Trace causation** from root cause to symptom
4. **Verify understanding** by explaining the chain

**Root Cause Template:**
- **Proximate Cause:** [immediate trigger]
- **Underlying Cause:** [deeper reason]
- **Contributing Factors:** [other influences]
- **Why it happened:** [explanation]
- **Why it manifested this way:** [explanation]

### Step 6: Solution Development
Create actionable fix:
1. **Immediate Fix**
   - What can be done right now?
   - Workaround or permanent fix?
   - Steps to implement

2. **Verification Plan**
   - How to confirm fix works?
   - What tests to run?
   - Success criteria

3. **Prevention**
   - How to prevent recurrence?
   - What process changes needed?
   - What validation to add?

### Step 7: Debug Report Generation
Document findings and solutions:
1. **Problem Summary** - Clear description
2. **Root Cause** - What actually went wrong
3. **Evidence** - Supporting data
4. **Solution** - Fix and verification
5. **Prevention** - Future safeguards

## Command Format

```
/debug [issue_description] [context_path]
```

**Arguments:**
- `issue_description`: Brief description of the problem
- `context_path`: (optional) Relevant directory/file path

## Debug Report Structure

```markdown
# Debug Report

## Problem Summary
**Issue:** [clear, concise description]
**Severity:** [Critical / High / Medium / Low]
**Impact:** [what's affected]
**First Observed:** [when/where]

## Symptoms Observed
1. [Symptom 1] - [details]
2. [Symptom 2] - [details]
3. [Symptom 3] - [details]

## Context
**Command Executed:**
```
[command and arguments]
```

**Environment:**
- Spec File: [path]
- Output Directory: [path]
- Iteration Count: [number]
- Mode: [single/batch/infinite]

**Recent History:**
- [Event 1]
- [Event 2]
- [Event 3]

## Investigation Process

### Hypotheses Considered
1. **[Hypothesis 1]:** [description]
   - Likelihood: [High/Medium/Low]
   - Test approach: [how to verify]

2. **[Hypothesis 2]:** [description]
   - Likelihood: [High/Medium/Low]
   - Test approach: [how to verify]

### Evidence Collected

#### [Evidence Category 1]
- **Finding:** [what was discovered]
- **Source:** [where it came from]
- **Significance:** [what it means]

#### [Evidence Category 2]
- **Finding:** [what was discovered]
- **Source:** [where it came from]
- **Significance:** [what it means]

### Hypotheses Eliminated
- [Hypothesis X] - **Eliminated because:** [contradictory evidence]

## Root Cause Analysis

### Root Cause
**Primary Cause:** [the fundamental issue]

**Explanation:**
[Detailed explanation of why this caused the problem]

**Causation Chain:**
1. [Root cause] led to →
2. [Intermediate effect] which caused →
3. [Proximate trigger] resulting in →
4. [Observed symptom]

### Contributing Factors
1. [Factor 1] - [how it contributed]
2. [Factor 2] - [how it contributed]

### Why It Wasn't Caught Earlier
[Explanation of what allowed this to occur]

## Solution

### Immediate Fix
**Action:** [what to do now]

**Steps:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Expected Outcome:**
[What should happen after fix]

### Verification Plan
**Tests to Run:**
1. [Test 1] - [expected result]
2. [Test 2] - [expected result]

**Success Criteria:**
- [Criterion 1]
- [Criterion 2]

### Long-Term Solution
**Process Improvements:**
1. [Improvement 1] - [rationale]
2. [Improvement 2] - [rationale]

**Prevention Measures:**
1. [Measure 1] - [how it prevents recurrence]
2. [Measure 2] - [how it prevents recurrence]

## Recommendations

### Immediate Actions
1. **[Action 1]** - [Priority: High/Medium/Low]
   - What: [description]
   - Why: [rationale]
   - How: [steps]

### Code/Configuration Changes
1. **[Change 1]**
   - File: [path]
   - Modification: [description]
   - Rationale: [why needed]

### Process Changes
1. **[Change 1]**
   - Current process: [description]
   - New process: [description]
   - Benefit: [improvement]

## Related Issues
- [Related Issue 1] - [relationship]
- [Related Issue 2] - [relationship]

## Lessons Learned
1. [Lesson 1] - [what we learned]
2. [Lesson 2] - [what we learned]

## Next Steps
1. [Step 1] - [owner] - [deadline]
2. [Step 2] - [owner] - [deadline]
3. [Step 3] - [owner] - [deadline]
```

## Common Debugging Scenarios

### Scenario 1: Generation Produces No Outputs
**Debugging Path:**
1. Check if orchestrator is parsing arguments correctly
2. Verify spec file is readable and valid
3. Check output directory permissions
4. Review sub-agent task definitions
5. Look for errors in orchestration logic

### Scenario 2: Outputs Don't Match Specification
**Debugging Path:**
1. Validate spec file with `/validate-spec`
2. Check if sub-agents received correct context
3. Review sub-agent creative assignments
4. Test outputs with `/test-output`
5. Analyze where spec interpretation diverged

### Scenario 3: Quality Below Standards
**Debugging Path:**
1. Run `/analyze` to identify quality patterns
2. Review quality standards in spec
3. Check sub-agent sophistication levels
4. Examine example iterations
5. Identify missing context or guidance

### Scenario 4: Duplicate or Similar Iterations
**Debugging Path:**
1. Check uniqueness constraints in spec
2. Review creative direction assignments
3. Analyze existing iterations with `/analyze`
4. Verify sub-agents received uniqueness guidance
5. Check if theme space is exhausted

### Scenario 5: Orchestration Hangs or Errors
**Debugging Path:**
1. Check for infinite loops in orchestrator logic
2. Verify resource availability
3. Review agent wave calculations
4. Check for context size issues
5. Look for syntax errors in commands

## Usage Examples

```bash
# Debug with general issue description
/debug "generation producing empty files"

# Debug with context path
/debug "quality issues in outputs" outputs/

# Debug orchestration problem
/debug "infinite loop not launching next wave"

# Debug spec-related issue
/debug "sub-agents misinterpreting requirements" specs/example_spec.md
```

## Chain-of-Thought Benefits

This utility uses explicit reasoning to:
- **Systematically diagnose** problems through structured investigation
- **Make debugging logic transparent** for learning and reproducibility
- **Provide clear causation chains** from root cause to symptom
- **Enable developers to understand** not just what's wrong, but why
- **Support systematic improvement** through lessons learned

## Execution Protocol

Now, execute the debugging process:

1. **Identify symptoms** - clearly define the problem
2. **Gather context** - collect relevant information
3. **Form hypotheses** - propose possible causes
4. **Collect evidence** - gather data to test hypotheses
5. **Analyze root cause** - determine fundamental issue
6. **Develop solution** - create actionable fix
7. **Generate report** - document findings and recommendations

Begin debugging the specified issue.
