gh-martybonacci-specswarm/commands/coordinate.md

description

description
Coordinate complex debugging workflows with logging, monitoring, and agent orchestration

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Execute systematic debugging coordination workflow:

1. Discovery Phase - Add logging and collect data
2. Analysis Phase - Correlate patterns and identify root causes
3. Orchestration Phase - Spawn specialist agents and coordinate fixes
4. Integration Phase - Verify fixes work together

Usage: /debug:coordinate <problem-description>

Example:

/debug:coordinate "navbar not updating after sign-in, sign-out not working, like button blank page"

---

Pre-Coordination Hook

echo "🐛 Debug Coordinator"
echo "==================="
echo ""
echo "Systematic debugging with logging, monitoring, and agent orchestration"
echo ""

# Record start time
COORD_START_TIME=$(date +%s)

# Get repository root
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

---

Execution Steps

Step 1: Parse Problem Description

# Get problem description from arguments
PROBLEM_DESC="$ARGUMENTS"

if [ -z "$PROBLEM_DESC" ]; then
    echo "❌ Error: Problem description required"
    echo ""
    echo "Usage: /debug:coordinate <problem-description>"
    echo ""
    echo "Example:"
    echo "/debug:coordinate \"navbar not updating, sign-out broken, like button error\""
    exit 1
fi

echo "📋 Problem: $PROBLEM_DESC"
echo ""

---

Step 2: Discovery Phase - Initial Analysis

Analyze the problem description to identify:

• How many distinct issues are mentioned
• Which domains might be affected
• Whether orchestration is appropriate

echo "🔍 Phase 1: Discovery & Analysis"
echo "================================"
echo ""

# Count potential bugs (look for separators like commas, "and", bullet points)
BUG_COUNT=$(echo "$PROBLEM_DESC" | tr ',' '\n' | tr ';' '\n' | grep -v '^$' | wc -l)

echo "Analyzing problem description..."
echo "  • Identified $BUG_COUNT potential issue(s)"
echo ""

# Create debug session directory
DEBUG_SESSION_ID=$(date +%Y%m%d-%H%M%S)
DEBUG_DIR="${REPO_ROOT}/.debug-sessions/${DEBUG_SESSION_ID}"
mkdir -p "$DEBUG_DIR"

echo "Created debug session: $DEBUG_SESSION_ID"
echo "Directory: $DEBUG_DIR"
echo ""

# Write problem description to session
cat > "$DEBUG_DIR/problem-description.md" <<EOF
# Debug Session: $DEBUG_SESSION_ID

**Created**: $(date)
**Problem Description**: $PROBLEM_DESC

## Issues Identified

EOF

# Parse individual issues
ISSUE_NUM=1
echo "$PROBLEM_DESC" | tr ',' '\n' | tr ';' '\n' | grep -v '^$' | while read -r ISSUE; do
    ISSUE_TRIMMED=$(echo "$ISSUE" | sed 's/^ *//g' | sed 's/ *$//g')
    if [ -n "$ISSUE_TRIMMED" ]; then
        echo "$ISSUE_NUM. $ISSUE_TRIMMED" >> "$DEBUG_DIR/problem-description.md"
        ISSUE_NUM=$((ISSUE_NUM + 1))
    fi
done

echo "✅ Problem analysis complete"
echo ""

---

Step 3: Determine Debugging Strategy

Based on the number of issues, decide whether to use orchestration:

echo "🎯 Determining debugging strategy..."
echo ""

if [ "$BUG_COUNT" -ge 3 ]; then
    STRATEGY="orchestrated"
    echo "Strategy: ORCHESTRATED (multi-bug scenario)"
    echo ""
    echo "Rationale:"
    echo "  • $BUG_COUNT distinct issues detected"
    echo "  • Parallel investigation will be faster"
    echo "  • Orchestrator recommended for 3+ bugs"
    echo ""
else
    STRATEGY="sequential"
    echo "Strategy: SEQUENTIAL (1-2 bugs)"
    echo ""
    echo "Rationale:"
    echo "  • $BUG_COUNT issue(s) detected"
    echo "  • Sequential debugging is efficient for small sets"
    echo ""
fi

# Save strategy to session
echo "**Strategy**: $STRATEGY" >> "$DEBUG_DIR/problem-description.md"
echo "" >> "$DEBUG_DIR/problem-description.md"

---

Step 4: Discovery Phase - Add Logging Strategy

Generate a logging strategy document that identifies where to add instrumentation:

Create a logging strategy specification:

Analyze the problem description and generate a comprehensive logging plan.

For each suspected issue:
1. Identify likely affected files/components
2. Specify logging points to add
3. Define what data to capture
4. Determine monitoring approach

**Output**: Create `$DEBUG_DIR/logging-strategy.md` with:
- Files to instrument
- Logging statements to add
- Data to capture
- Monitoring commands

Logging Strategy Template:

# Logging Strategy

## Issue 1: [Issue Description]

### Suspected Files
- `path/to/file1.ts` - [reason]
- `path/to/file2.ts` - [reason]

### Logging Points

**File**: `path/to/file1.ts`
**Location**: Line XX (in function `functionName`)
**Log Statement**:
```typescript
console.log('[DEBUG-1] FunctionName:', { variable1, variable2, context })

Purpose: Capture state at critical point

Monitoring

• Watch for: [DEBUG-1] in console
• Expected output: Values should be X
• Error indicators: null, undefined, unexpected values

---

Issue 2: [Issue Description]

...

```bash
echo "📝 Phase 2: Logging Strategy"
echo "============================"
echo ""

echo "Generating logging strategy..."
echo ""
echo "ACTION REQUIRED: Analyze the problem and create logging strategy"
echo ""
echo "Create file: $DEBUG_DIR/logging-strategy.md"
echo ""
echo "For each issue in the problem description:"
echo "  1. Identify suspected files/components"
echo "  2. Determine strategic logging points"
echo "  3. Specify what data to capture"
echo "  4. Define monitoring approach"
echo ""
echo "Use template from: plugins/debug-coordinate/templates/logging-strategy-template.md"
echo ""

After logging strategy is created, proceed to implementation:

echo "After creating logging strategy, implement the logging:"
echo ""
echo "  1. Add logging statements to suspected files"
echo "  2. Ensure logs are easily searchable (use prefixes like [DEBUG-1])"
echo "  3. Capture relevant context (variables, state, params)"
echo "  4. Commit logging additions (so they can be reverted later)"
echo ""

---

Step 5: Analysis Phase - Run & Monitor

echo "📊 Phase 3: Monitor & Analyze"
echo "============================="
echo ""

echo "Next steps:"
echo "  1. Start the application (if not running)"
echo "  2. Reproduce each issue"
echo "  3. Capture log output to: $DEBUG_DIR/logs/"
echo "  4. Analyze patterns and identify root causes"
echo ""
echo "Monitoring commands:"
echo "  • Save logs: [command] 2>&1 | tee $DEBUG_DIR/logs/session.log"
echo "  • Watch specific pattern: tail -f [logfile] | grep DEBUG"
echo "  • Filter errors: grep -E 'ERROR|WARN|DEBUG' [logfile]"
echo ""

Create analysis template:

cat > "$DEBUG_DIR/analysis-template.md" <<'EOF'
# Debug Analysis

## Issue 1: [Description]

### Log Evidence

[Paste relevant log output]

### Root Cause
[What is causing this issue?]

**File**: path/to/file.ts
**Line**: XX
**Problem**: [Specific issue - e.g., variable undefined, wrong condition, etc.]

### Domain
- [ ] Backend
- [ ] Frontend
- [ ] Database
- [ ] Config
- [ ] Testing

### Fix Strategy
[How to fix this issue]

---

## Issue 2: [Description]
...

---

## Summary

**Total Issues**: X
**Domains Affected**: [list]
**Orchestration Recommended**: Yes/No
EOF

echo "Created analysis template: $DEBUG_DIR/analysis-template.md"
echo ""
echo "Fill in this template as you analyze logs and identify root causes"
echo ""

---

Step 6: Orchestration Phase - Generate Fix Plan

Once root causes are identified, generate orchestration plan:

echo "🎯 Phase 4: Orchestration Planning"
echo "==================================="
echo ""

if [ "$STRATEGY" = "orchestrated" ]; then
    echo "Generating orchestration plan for parallel fixes..."
    echo ""

    cat > "$DEBUG_DIR/orchestration-plan.md" <<'EOF'
# Orchestration Plan

## Execution Strategy

**Mode**: Parallel
**Agents**: [Number based on domains]

---

## Agent Assignments

### Agent 1: [Domain] Track
**Responsibility**: [Description]
**Issues**: #1, #3
**Files to Modify**:
- path/to/file1.ts
- path/to/file2.ts

**Changes Required**:
1. [Specific change 1]
2. [Specific change 2]

**Dependencies**: None (can run in parallel)

---

### Agent 2: [Domain] Track
**Responsibility**: [Description]
**Issues**: #2, #4
**Files to Modify**:
- path/to/file3.tsx
- path/to/file4.tsx

**Changes Required**:
1. [Specific change 1]
2. [Specific change 2]

**Dependencies**: None (can run in parallel)

---

## Coordination Points

### Server Restarts
- After Agent 1 completes (backend changes)
- After Agent 2 completes (if needed)

### Integration Testing
- After all agents complete
- Run full test suite
- Manual verification of each fix

---

## Success Criteria
- [ ] All issues resolved
- [ ] No new regressions
- [ ] Tests pass
- [ ] Application works as expected
EOF

    echo "✅ Orchestration plan template created: $DEBUG_DIR/orchestration-plan.md"
    echo ""
    echo "ACTION REQUIRED: Fill in orchestration plan based on analysis"
    echo ""
    echo "Then launch orchestrator:"
    echo "  /project-orchestrator:debug --plan=$DEBUG_DIR/orchestration-plan.md"
    echo ""

else
    echo "Sequential debugging workflow (1-2 bugs)"
    echo ""
    echo "Fix issues sequentially using /speclab:bugfix for each"
    echo ""
fi

---

Step 7: Integration Phase - Verification

echo "✅ Phase 5: Integration & Verification"
echo "======================================="
echo ""

echo "After fixes are implemented:"
echo ""
echo "1. Run integration tests"
echo "2. Manually verify each issue is fixed"
echo "3. Check for new regressions"
echo "4. Remove debug logging (or keep if useful)"
echo "5. Document learnings"
echo ""
echo "Verification checklist: $DEBUG_DIR/verification-checklist.md"
echo ""

cat > "$DEBUG_DIR/verification-checklist.md" <<'EOF'
# Verification Checklist

## Issue Verification

- [ ] Issue 1: [Description] - FIXED
- [ ] Issue 2: [Description] - FIXED
- [ ] Issue 3: [Description] - FIXED

## Regression Testing

- [ ] Existing tests still pass
- [ ] No new errors in console
- [ ] No performance degradation
- [ ] All user flows work correctly

## Cleanup

- [ ] Remove temporary debug logging (or commit if useful)
- [ ] Update documentation
- [ ] Create regression tests for each fix
- [ ] Document learnings

## Metrics

**Debugging Time**: [X hours]
**Number of Issues Fixed**: [X]
**Strategy Used**: [Sequential/Orchestrated]
**Time Savings** (if orchestrated): [X%]
EOF

echo "Created verification checklist"
echo ""

---

Post-Coordination Hook

echo ""
echo "📊 Debug Coordination Summary"
echo "=============================="
echo ""

# Calculate duration
COORD_END_TIME=$(date +%s)
COORD_DURATION=$((COORD_END_TIME - COORD_START_TIME))
COORD_MINUTES=$((COORD_DURATION / 60))

echo "Session ID: $DEBUG_SESSION_ID"
echo "Duration: ${COORD_MINUTES}m ${COORD_DURATION}s"
echo "Strategy: $STRATEGY"
echo "Issues: $BUG_COUNT"
echo ""
echo "Artifacts Created:"
echo "  • $DEBUG_DIR/problem-description.md"
echo "  • $DEBUG_DIR/logging-strategy.md"
echo "  • $DEBUG_DIR/analysis-template.md"
if [ "$STRATEGY" = "orchestrated" ]; then
    echo "  • $DEBUG_DIR/orchestration-plan.md"
fi
echo "  • $DEBUG_DIR/verification-checklist.md"
echo ""
echo "📈 Next Steps:"
echo ""
if [ "$STRATEGY" = "orchestrated" ]; then
    echo "ORCHESTRATED WORKFLOW:"
    echo "  1. Fill in logging-strategy.md"
    echo "  2. Implement logging and run application"
    echo "  3. Analyze logs and complete analysis-template.md"
    echo "  4. Fill in orchestration-plan.md"
    echo "  5. Launch orchestrator: /project-orchestrator:debug --plan=$DEBUG_DIR/orchestration-plan.md"
    echo "  6. Verify all fixes with verification-checklist.md"
else
    echo "SEQUENTIAL WORKFLOW:"
    echo "  1. Fill in logging-strategy.md"
    echo "  2. Implement logging and run application"
    echo "  3. Analyze logs and identify root causes"
    echo "  4. Fix issues one by one using /speclab:bugfix"
    echo "  5. Verify with verification-checklist.md"
fi
echo ""
echo "💡 Tip: This structured approach ensures:"
echo "  • Systematic investigation (not random debugging)"
echo "  • Clear documentation of findings"
echo "  • Efficient parallelization (when possible)"
echo "  • Verifiable results"
echo ""

---

Success Criteria

✅ Problem description parsed ✅ Debug session created ✅ Strategy determined (sequential vs orchestrated) ✅ Logging strategy template created ✅ Analysis template created ✅ Orchestration plan template created (if needed) ✅ Verification checklist created ✅ Clear next steps provided

---

Error Handling

If no problem description provided:

• Display usage example
• Exit with error

If repository not detected:

• Create debug session in current directory
• Warn user about missing git context

---

Design Philosophy

Based on learnings from 2025-10-14-orchestrator-missed-opportunity.md:

1. Systematic Over Random: Structured phases prevent random debugging
2. Logging First: Add instrumentation before making changes
3. Parallel When Possible: 3+ bugs → orchestrate
4. Document Everything: Create audit trail for learnings
5. Verify Thoroughly: Checklists ensure nothing missed

---

This plugin transforms chaotic debugging into systematic investigation with clear orchestration opportunities.