gh-schovi-claude-schovi-schovi/commands/debug.md

---
description: Deep debugging workflow with root cause analysis, problematic flow identification, and single fix proposal
argument-hint: [jira-id|pr-url|#pr-number|github-issue-url|description] [--input PATH] [--output PATH] [--no-file] [--quiet] [--work-dir PATH]
allowed-tools: ["Read", "Write", "Task", "ExitPlanMode"]
---

# Problem Debugger Workflow

You are performing **deep debugging and root cause analysis** for a bug or production issue using the **executor pattern**. Follow this structured workflow to identify the problematic flow and propose a single, targeted fix.

**Key Innovation**: The debug-executor subagent performs ALL work (context fetching, debugging, fix generation) in isolated context, keeping main context clean.

---

## ⚙️ MODE ENFORCEMENT

**CRITICAL**: This command operates in **PLAN MODE** throughout Phases 1-2 (argument parsing and executor invocation). You MUST use the **ExitPlanMode tool** before Phase 3 (output handling) to transition from analysis to execution.

**Workflow**:
```
┌──────────────────────────────────┐
│  PLAN MODE (Read-only)           │
│  Phases 1-2: Setup & Execute     │
└──────────────────────────────────┘
              ↓
      [ExitPlanMode Tool]
              ↓
┌──────────────────────────────────┐
│  EXECUTION MODE (Write)          │
│  Phases 3-4: Output & Completion │
└──────────────────────────────────┘
```

---

## PHASE 1: ARGUMENT PARSING

Use lib/argument-parser.md:

```
Configuration:
  command_name: "debug"
  command_label: "Debug-Problem"

  positional:
    - name: "problem_input"
      description: "Jira ID, GitHub URL, error description"
      required: false

  flags:
    - name: "--input"
      type: "path"
      description: "Read problem description from file (error log, stack trace)"
    - name: "--output"
      type: "path"
      description: "Custom output file path for debug report"
    - name: "--work-dir"
      type: "path"
      description: "Custom work directory"
    - name: "--no-file"
      type: "boolean"
      description: "Skip file creation, terminal only"
    - name: "--quiet"
      type: "boolean"
      description: "Suppress terminal output"

  validation:
    - --output and --no-file are mutually exclusive
    - At least one input source required (positional or --input)
```

**Store parsed values:**
- `problem_input`: Positional argument or --input file content
- `output_path`: --output value or null
- `work_dir`: --work-dir value or null
- `file_output`: true (unless --no-file)
- `terminal_output`: true (unless --quiet)

---

## PHASE 2: EXECUTE DEBUG (Isolated Context)

**Objective**: Spawn debug-executor subagent to perform ALL debugging work in isolated context.

**Use Task tool with debug-executor**:

```
Task tool configuration:
  subagent_type: "schovi:debug-executor:debug-executor"
  model: "sonnet"
  description: "Execute debug workflow"
  prompt: |
    PROBLEM REFERENCE: [problem_input]

    CONFIGURATION:
    - identifier: [auto-detect from problem_input or generate slug]
    - severity: [auto-detect or "Medium"]

    Execute complete debugging workflow:
    1. Fetch external context (Jira/GitHub if applicable)
    2. Deep debugging & root cause analysis (Explore subagent, very thorough mode)
    3. Generate fix proposal (location, code changes, testing, rollout)

    Return structured fix proposal (~1500-2500 tokens).
```

**Expected output from executor**:
- Complete structured fix proposal markdown (~1500-2500 tokens)
- Includes: problem summary, root cause with execution flow, fix proposal with code changes, testing strategy, rollout plan
- All file references in file:line format
- Already formatted

**Store executor output**:
- `fix_proposal_output`: Complete markdown from executor
- `identifier`: Extract from fix proposal header or use fallback

---

## PHASE 3: EXIT PLAN MODE

**CRITICAL**: Before proceeding to output handling, use ExitPlanMode tool.

```
ExitPlanMode tool:
  plan: |
    # Debugging Complete

    Root cause analysis and fix proposal completed via debug-executor subagent.

    **Identifier**: [identifier]
    **Problem**: [Brief description]

    ## Key Findings

    - Problem context fetched and analyzed
    - Deep debugging completed (Explore subagent, very thorough mode)
    - Root cause identified with execution flow trace
    - Fix location pinpointed with file:line
    - Code changes proposed with testing strategy

    ## Next Steps

    1. Save fix proposal to work folder
    2. Display summary to user
    3. Offer to implement fix
```

**Wait for user approval before proceeding to Phase 4.**

---

## PHASE 4: OUTPUT HANDLING & WORK FOLDER

### Step 4.1: Work Folder Resolution

Use lib/work-folder.md:

```
Configuration:
  mode: "auto-detect"

  identifier: [identifier extracted from fix_proposal_output or input]
  description: [extract problem title from fix_proposal_output]

  workflow_type: "debug"
  current_step: "debug"

  custom_work_dir: [work_dir from argument parsing, or null]

Output (store for use below):
  work_folder: [path from library, e.g., ".WIP/EC-1234-feature"]
  metadata_file: [path from library, e.g., ".WIP/EC-1234-feature/.metadata.json"]
  output_file: [path from library, e.g., ".WIP/EC-1234-feature/debug-EC-1234.md"]
  identifier: [identifier from library]
  is_new: [true/false from library]
```

**Store the returned values for steps below.**

### Step 4.2: Write Debug Output

**If `file_output == true` (default unless --no-file):**

Use Write tool:
```
file_path: [output_file from Step 4.1]
content: [fix_proposal_output from Phase 3]
```

**If write succeeds:**
```
📄 Fix proposal saved to: [output_file]
```

**If write fails or --no-file:**
Skip file creation, continue to terminal output.

### Step 4.3: Update Metadata

**If work_folder exists and file was written:**

Read current metadata:
```bash
cat [metadata_file from Step 4.1]
```

Update fields:
```json
{
  ...existing fields,
  "workflow": {
    ...existing.workflow,
    "completed": ["debug"],
    "current": "debug"
  },
  "files": {
    "debug": "debug-[identifier].md"
  },
  "timestamps": {
    ...existing.timestamps,
    "lastModified": "[current timestamp]"
  }
}
```

Get current timestamp:
```bash
date -u +"%Y-%m-%dT%H:%M:%SZ"
```

Write updated metadata:
```
Write tool:
  file_path: [metadata_file]
  content: [updated JSON]
```

### Step 4.4: Terminal Output

**If `terminal_output == true` (default unless --quiet):**

Display:
```markdown
# 🐛 Debug Complete: [identifier]

Root cause analysis and fix proposal ready.

## 🔍 Root Cause

[Extract root cause summary from fix_proposal_output - 2-3 sentences]

## 💡 Fix Location

[Extract fix location from output - file:line]

## 📁 Output

Fix proposal saved to: `[output_file]`
Work folder: `[work_folder]`

## 🚀 Next Steps

Ready to implement the fix:

```bash
# Review the fix proposal first
cat [output_file]

# Then implement (coming soon)
/schovi:implement --input debug-[identifier].md
```
```

---

## PHASE 5: COMPLETION

**Final Message**:
```
✅ Debugging completed successfully!

🐛 Root cause identified for [identifier]
💡 Fix proposal generated with code changes
📁 Saved to: [file_path]

🚀 Ready to implement the fix? Review the proposal and run:
   /schovi:implement --input debug-[identifier].md
```

**Command complete.**

---

## ERROR HANDLING

### Input Processing Errors
- **No input provided**: Ask user for Jira ID, GitHub URL, or error description
- **Invalid format**: Report error, show format examples
- **File not found**: Report error, ask for correct path

### Executor Errors
- **Executor failed**: Report error with details from subagent
- **Validation failed**: Check fix_proposal_output has required sections
- **Token budget exceeded**: Executor handles compression, shouldn't happen

### Output Errors
- **File write failed**: Report error, offer terminal-only output
- **Work folder error**: Use fallback location or report error

---

## QUALITY GATES

Before completing, verify:

- [ ] Input processed successfully with clear problem reference
- [ ] Executor invoked and completed successfully
- [ ] Fix proposal output received (~1500-2500 tokens)
- [ ] Output contains all required sections
- [ ] Root cause identified with execution flow
- [ ] Fix location specified with file:line
- [ ] Code changes provided (before/after)
- [ ] Testing strategy included
- [ ] Rollout plan included
- [ ] All file references use file:line format
- [ ] File saved to work folder (unless --no-file)
- [ ] Metadata updated
- [ ] Terminal output displayed (unless --quiet)

---

## NOTES

**Design Philosophy**:
- **Executor pattern**: ALL work (fetch + debug + generate) happens in isolated context
- **Main context stays clean**: Only sees final formatted output (~1.5-2.5k tokens)
- **Token efficiency**: 96% reduction in main context (from ~63k to ~2.5k tokens)
- **Consistent experience**: User sees same output, just more efficient internally

**Token Benefits**:
- Before: Main context sees input + debugging (60k) + generation = ~63k tokens
- After: Main context sees only final output = ~2.5k tokens
- Savings: 60.5k tokens (96% reduction)

**Integration**:
- Input from: Jira, GitHub issues/PRs, error descriptions, stack traces
- Output to: Work folder with metadata
- Next command: Implement for applying the fix

**Executor Capabilities**:
- Spawns jira-analyzer, gh-issue-analyzer for external context
- Spawns Explore subagent for very thorough debugging
- Generates fix proposal with code changes
- All in isolated context, returns clean result

---

**Command Version**: 2.0 (Executor Pattern)
**Last Updated**: 2025-11-07
**Dependencies**:
- `lib/argument-parser.md`
- `lib/work-folder.md`
- `schovi/agents/debug-executor/AGENT.md`