Claude-Code-Workflow/.claude/commands/workflow/debug-with-file.md

---
name: debug-with-file
description: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction
argument-hint: "[-y|--yes] \"bug description or error message\""
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
---

## Auto Mode

When `--yes` or `-y`: Auto-confirm all decisions (hypotheses, fixes, iteration), use recommended settings.

# Workflow Debug-With-File Command (/workflow:debug-with-file)

## Overview

Enhanced evidence-based debugging with **documented exploration process**. Records understanding evolution, consolidates insights, and uses Gemini to correct misunderstandings.

**Core workflow**: Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify

**Scope**: Adds temporary debug logging to observe program state; cleans up all instrumentation after resolution. Does NOT execute code injection, security testing, or modify program behavior.

**Key enhancements over /workflow:debug**:
- **understanding.md**: Timeline of exploration and learning
- **Gemini-assisted correction**: Validates and corrects hypotheses
- **Consolidation**: Simplifies proven-wrong understanding to avoid clutter
- **Learning retention**: Preserves what was learned, even from failed attempts

## Usage

```bash
/workflow:debug-with-file <BUG_DESCRIPTION>

# Arguments
<bug-description>          Bug description, error message, or stack trace (required)
```

## Execution Process

```
Session Detection:
   ├─ Check if debug session exists for this bug
   ├─ EXISTS + understanding.md exists → Continue mode
   └─ NOT_FOUND → Explore mode

Explore Mode:
   ├─ Locate error source in codebase
   ├─ Document initial understanding in understanding.md
   ├─ Generate testable hypotheses with Gemini validation
   ├─ Add NDJSON debug logging statements
   └─ Output: Hypothesis list + await user reproduction

Analyze Mode:
   ├─ Parse debug.log, validate each hypothesis
   ├─ Use Gemini to analyze evidence and correct understanding
   ├─ Update understanding.md with:
   │   ├─ New evidence
   │   ├─ Corrected misunderstandings (strikethrough + correction)
   │   └─ Consolidated current understanding
   └─ Decision:
       ├─ Confirmed → Fix root cause
       ├─ Inconclusive → Add more logging, iterate
       └─ All rejected → Gemini-assisted new hypotheses

Fix & Cleanup:
   ├─ Apply fix based on confirmed hypothesis
   ├─ User verifies
   ├─ Document final understanding + lessons learned
   ├─ Remove debug instrumentation
   └─ If not fixed → Return to Analyze mode
```

## Implementation

### Session Setup & Mode Detection

```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 30)
const dateStr = getUtc8ISOString().substring(0, 10)

const sessionId = `DBG-${bugSlug}-${dateStr}`
const sessionFolder = `.workflow/.debug/${sessionId}`
const debugLogPath = `${sessionFolder}/debug.log`
const understandingPath = `${sessionFolder}/understanding.md`
const hypothesesPath = `${sessionFolder}/hypotheses.json`

// Auto-detect mode
const sessionExists = fs.existsSync(sessionFolder)
const hasUnderstanding = sessionExists && fs.existsSync(understandingPath)
const logHasContent = sessionExists && fs.existsSync(debugLogPath) && fs.statSync(debugLogPath).size > 0

const mode = logHasContent ? 'analyze' : (hasUnderstanding ? 'continue' : 'explore')

if (!sessionExists) {
  bash(`mkdir -p ${sessionFolder}`)
}
```

---

### Explore Mode

**Step 1.1: Locate Error Source**

```javascript
// Extract keywords from bug description
const keywords = extractErrorKeywords(bug_description)

// Search codebase for error locations
const searchResults = []
for (const keyword of keywords) {
  const results = Grep({ pattern: keyword, path: ".", output_mode: "content", "-C": 3 })
  searchResults.push({ keyword, results })
}

// Identify affected files and functions
const affectedLocations = analyzeSearchResults(searchResults)
```

**Step 1.2: Document Initial Understanding**

Create `understanding.md` with exploration timeline:

```markdown
# Understanding Document

**Session ID**: ${sessionId}
**Bug Description**: ${bug_description}
**Started**: ${getUtc8ISOString()}

---

## Exploration Timeline

### Iteration 1 - Initial Exploration (${timestamp})

#### Current Understanding

Based on bug description and initial code search:

- Error pattern: ${errorPattern}
- Affected areas: ${affectedLocations.map(l => l.file).join(', ')}
- Initial hypothesis: ${initialThoughts}

#### Evidence from Code Search

${searchResults.map(r => `
**Keyword: "${r.keyword}"**
- Found in: ${r.results.files.join(', ')}
- Key findings: ${r.insights}
`).join('\n')}

#### Next Steps

- Generate testable hypotheses
- Add instrumentation
- Await reproduction

---

## Current Consolidated Understanding

${initialConsolidatedUnderstanding}
```

**Step 1.3: Gemini-Assisted Hypothesis Generation**

```bash
ccw cli -p "
PURPOSE: Generate debugging hypotheses for: ${bug_description}
Success criteria: Testable hypotheses with clear evidence criteria

TASK:
• Analyze error pattern and code search results
• Identify 3-5 most likely root causes
• For each hypothesis, specify:
  - What might be wrong
  - What evidence would confirm/reject it
  - Where to add instrumentation
• Rank by likelihood

MODE: analysis

CONTEXT: @${sessionFolder}/understanding.md | Search results in understanding.md

EXPECTED:
- Structured hypothesis list (JSON format)
- Each hypothesis with: id, description, testable_condition, logging_point, evidence_criteria
- Likelihood ranking (1=most likely)

CONSTRAINTS: Focus on testable conditions
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
```

Save Gemini output to `hypotheses.json`:

```json
{
  "iteration": 1,
  "timestamp": "2025-01-21T10:00:00+08:00",
  "hypotheses": [
    {
      "id": "H1",
      "description": "Data structure mismatch - expected key not present",
      "testable_condition": "Check if target key exists in dict",
      "logging_point": "file.py:func:42",
      "evidence_criteria": {
        "confirm": "data shows missing key",
        "reject": "key exists with valid value"
      },
      "likelihood": 1,
      "status": "pending"
    }
  ],
  "gemini_insights": "...",
  "corrected_assumptions": []
}
```

**Step 1.4: Add NDJSON Debug Logging**

For each hypothesis, add temporary logging statements to observe program state at key execution points. Use NDJSON format for structured log parsing. These are read-only observations that do not modify program behavior.

**Step 1.5: Update understanding.md**

Append hypothesis section:

```markdown
#### Hypotheses Generated (Gemini-Assisted)

${hypotheses.map(h => `
**${h.id}** (Likelihood: ${h.likelihood}): ${h.description}
- Logging at: ${h.logging_point}
- Testing: ${h.testable_condition}
- Evidence to confirm: ${h.evidence_criteria.confirm}
- Evidence to reject: ${h.evidence_criteria.reject}
`).join('\n')}

**Gemini Insights**: ${geminiInsights}
```

---

### Analyze Mode

**Step 2.1: Parse Debug Log**

```javascript
// Parse NDJSON log
const entries = Read(debugLogPath).split('\n')
  .filter(l => l.trim())
  .map(l => JSON.parse(l))

// Group by hypothesis
const byHypothesis = groupBy(entries, 'hid')
```

**Step 2.2: Gemini-Assisted Evidence Analysis**

```bash
ccw cli -p "
PURPOSE: Analyze debug log evidence to validate/correct hypotheses for: ${bug_description}
Success criteria: Clear verdict per hypothesis + corrected understanding

TASK:
• Parse log entries by hypothesis
• Evaluate evidence against expected criteria
• Determine verdict: confirmed | rejected | inconclusive
• Identify incorrect assumptions from previous understanding
• Suggest corrections to understanding

MODE: analysis

CONTEXT:
@${debugLogPath}
@${understandingPath}
@${hypothesesPath}

EXPECTED:
- Per-hypothesis verdict with reasoning
- Evidence summary
- List of incorrect assumptions with corrections
- Updated consolidated understanding
- Root cause if confirmed, or next investigation steps

CONSTRAINTS: Evidence-based reasoning only, no speculation
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause
```

**Step 2.3: Update Understanding with Corrections**

Append new iteration to `understanding.md`:

```markdown
### Iteration ${n} - Evidence Analysis (${timestamp})

#### Log Analysis Results

${results.map(r => `
**${r.id}**: ${r.verdict.toUpperCase()}
- Evidence: ${JSON.stringify(r.evidence)}
- Reasoning: ${r.reason}
`).join('\n')}

#### Corrected Understanding

Previous misunderstandings identified and corrected:

${corrections.map(c => `
- ~~${c.wrong}~~ → ${c.corrected}
  - Why wrong: ${c.reason}
  - Evidence: ${c.evidence}
`).join('\n')}

#### New Insights

${newInsights.join('\n- ')}

#### Gemini Analysis

${geminiAnalysis}

${confirmedHypothesis ? `
#### Root Cause Identified

**${confirmedHypothesis.id}**: ${confirmedHypothesis.description}

Evidence supporting this conclusion:
${confirmedHypothesis.supportingEvidence}
` : `
#### Next Steps

${nextSteps}
`}

---

## Current Consolidated Understanding (Updated)

${consolidatedUnderstanding}
```

**Step 2.4: Consolidate Understanding**

At the bottom of `understanding.md`, update the consolidated section:

- Remove or simplify proven-wrong assumptions
- Keep them in strikethrough for reference
- Focus on current valid understanding
- Avoid repeating details from timeline

```markdown
## Current Consolidated Understanding

### What We Know

- ${validUnderstanding1}
- ${validUnderstanding2}

### What Was Disproven

- ~~Initial assumption: ${wrongAssumption}~~ (Evidence: ${disproofEvidence})

### Current Investigation Focus

${currentFocus}

### Remaining Questions

- ${openQuestion1}
- ${openQuestion2}
```

**Step 2.5: Update hypotheses.json**

```json
{
  "iteration": 2,
  "timestamp": "2025-01-21T10:15:00+08:00",
  "hypotheses": [
    {
      "id": "H1",
      "status": "rejected",
      "verdict_reason": "Evidence shows key exists with valid value",
      "evidence": {...}
    },
    {
      "id": "H2",
      "status": "confirmed",
      "verdict_reason": "Log data confirms timing issue",
      "evidence": {...}
    }
  ],
  "gemini_corrections": [
    {
      "wrong_assumption": "...",
      "corrected_to": "...",
      "reason": "..."
    }
  ]
}
```

---

### Fix & Verification

**Step 3.1: Apply Fix**

(Same as original debug command)

**Step 3.2: Document Resolution**

Append to `understanding.md`:

```markdown
### Iteration ${n} - Resolution (${timestamp})

#### Fix Applied

- Modified files: ${modifiedFiles.join(', ')}
- Fix description: ${fixDescription}
- Root cause addressed: ${rootCause}

#### Verification Results

${verificationResults}

#### Lessons Learned

What we learned from this debugging session:

1. ${lesson1}
2. ${lesson2}
3. ${lesson3}

#### Key Insights for Future

- ${insight1}
- ${insight2}
```

**Step 3.3: Cleanup**

Remove all temporary debug logging statements added during investigation. Verify no instrumentation code remains in production code.

---

## Session Folder Structure

```
.workflow/.debug/DBG-{slug}-{date}/
├── debug.log           # NDJSON log (execution evidence)
├── understanding.md    # NEW: Exploration timeline + consolidated understanding
├── hypotheses.json     # NEW: Hypothesis history with verdicts
└── resolution.md       # Optional: Final summary
```

## Understanding Document Template

```markdown
# Understanding Document

**Session ID**: DBG-xxx-2025-01-21
**Bug Description**: [original description]
**Started**: 2025-01-21T10:00:00+08:00

---

## Exploration Timeline

### Iteration 1 - Initial Exploration (2025-01-21 10:00)

#### Current Understanding
...

#### Evidence from Code Search
...

#### Hypotheses Generated (Gemini-Assisted)
...

### Iteration 2 - Evidence Analysis (2025-01-21 10:15)

#### Log Analysis Results
...

#### Corrected Understanding
- ~~[wrong]~~ → [corrected]

#### Gemini Analysis
...

---

## Current Consolidated Understanding

### What We Know
- [valid understanding points]

### What Was Disproven
- ~~[disproven assumptions]~~

### Current Investigation Focus
[current focus]

### Remaining Questions
- [open questions]
```

## Iteration Flow

```
First Call (/workflow:debug-with-file "error"):
   ├─ No session exists → Explore mode
   ├─ Extract error keywords, search codebase
   ├─ Document initial understanding in understanding.md
   ├─ Use Gemini to generate hypotheses
   ├─ Add logging instrumentation
   └─ Await user reproduction

After Reproduction (/workflow:debug-with-file "error"):
   ├─ Session exists + debug.log has content → Analyze mode
   ├─ Parse log, use Gemini to evaluate hypotheses
   ├─ Update understanding.md with:
   │   ├─ Evidence analysis results
   │   ├─ Corrected misunderstandings (strikethrough)
   │   ├─ New insights
   │   └─ Updated consolidated understanding
   ├─ Update hypotheses.json with verdicts
   └─ Decision:
       ├─ Confirmed → Fix → Document resolution
       ├─ Inconclusive → Add logging, document next steps
       └─ All rejected → Gemini-assisted new hypotheses

Output:
   ├─ .workflow/.debug/DBG-{slug}-{date}/debug.log
   ├─ .workflow/.debug/DBG-{slug}-{date}/understanding.md (evolving document)
   └─ .workflow/.debug/DBG-{slug}-{date}/hypotheses.json (history)
```

## Gemini Integration Points

### 1. Hypothesis Generation (Explore Mode)

**Purpose**: Generate evidence-based, testable hypotheses

**Prompt Pattern**:
```
PURPOSE: Generate debugging hypotheses + evidence criteria
TASK: Analyze error + code → testable hypotheses with clear pass/fail criteria
CONTEXT: @understanding.md (search results)
EXPECTED: JSON with hypotheses, likelihood ranking, evidence criteria
```

### 2. Evidence Analysis (Analyze Mode)

**Purpose**: Validate hypotheses and correct misunderstandings

**Prompt Pattern**:
```
PURPOSE: Analyze debug log evidence + correct understanding
TASK: Evaluate each hypothesis → identify wrong assumptions → suggest corrections
CONTEXT: @debug.log @understanding.md @hypotheses.json
EXPECTED: Verdicts + corrections + updated consolidated understanding
```

### 3. New Hypothesis Generation (After All Rejected)

**Purpose**: Generate new hypotheses based on what was disproven

**Prompt Pattern**:
```
PURPOSE: Generate new hypotheses given disproven assumptions
TASK: Review rejected hypotheses → identify knowledge gaps → new investigation angles
CONTEXT: @understanding.md (with disproven section) @hypotheses.json
EXPECTED: New hypotheses avoiding previously rejected paths
```

## Error Correction Mechanism

### Correction Format in understanding.md

```markdown
#### Corrected Understanding

- ~~Assumed dict key "config" was missing~~ → Key exists, but value is None
  - Why wrong: Only checked existence, not value validity
  - Evidence: H1 log shows {"config": null, "exists": true}

- ~~Thought error occurred in initialization~~ → Error happens during runtime update
  - Why wrong: Stack trace misread as init code
  - Evidence: H2 timestamp shows 30s after startup
```

### Consolidation Rules

When updating "Current Consolidated Understanding":

1. **Simplify disproven items**: Move to "What Was Disproven" with single-line summary
2. **Keep valid insights**: Promote confirmed findings to "What We Know"
3. **Avoid duplication**: Don't repeat timeline details in consolidated section
4. **Focus on current state**: What do we know NOW, not the journey
5. **Preserve key corrections**: Keep important wrong→right transformations for learning

**Bad (cluttered)**:
```markdown
## Current Consolidated Understanding

In iteration 1 we thought X, but in iteration 2 we found Y, then in iteration 3...
Also we checked A and found B, and then we checked C...
```

**Good (consolidated)**:
```markdown
## Current Consolidated Understanding

### What We Know
- Error occurs during runtime update, not initialization
- Config value is None (not missing key)

### What Was Disproven
- ~~Initialization error~~ (Timing evidence)
- ~~Missing key hypothesis~~ (Key exists)

### Current Investigation Focus
Why is config value None during update?
```

## Post-Completion Expansion

完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`

---

## Error Handling

| Situation | Action |
|-----------|--------|
| Empty debug.log | Verify reproduction triggered the code path |
| All hypotheses rejected | Use Gemini to generate new hypotheses based on disproven assumptions |
| Fix doesn't work | Document failed fix attempt, iterate with refined understanding |
| >5 iterations | Review consolidated understanding, escalate to `/workflow:lite-fix` with full context |
| Gemini unavailable | Fallback to manual hypothesis generation, document without Gemini insights |
| Understanding too long | Consolidate aggressively, archive old iterations to separate file |

## Comparison with /workflow:debug

| Feature | /workflow:debug | /workflow:debug-with-file |
|---------|-----------------|---------------------------|
| NDJSON debug logging | ✅ | ✅ |
| Hypothesis generation | Manual | Gemini-assisted |
| Exploration documentation | ❌ | ✅ understanding.md |
| Understanding evolution | ❌ | ✅ Timeline + corrections |
| Error correction | ❌ | ✅ Strikethrough + reasoning |
| Consolidated learning | ❌ | ✅ Current understanding section |
| Hypothesis history | ❌ | ✅ hypotheses.json |
| Gemini validation | ❌ | ✅ At key decision points |

## Usage Recommendations (Requires User Confirmation)

**Use `Skill(skill="workflow:debug-with-file", args="\"bug description\"")` when:**
- Complex bugs requiring multiple investigation rounds
- Learning from debugging process is valuable
- Team needs to understand debugging rationale
- Bug might recur, documentation helps prevention

**Use `Skill(skill="ccw-debug", args="--mode cli \"issue\"")` when:**
- Simple, quick bugs
- One-off issues
- Documentation overhead not needed