# Debugging-Coach

> Structured, repeatable debugging methodology with automated analysis and metrics tracking

- Author: j-dev-nz
- Repository: ruedaclubnz/ActiveSchedule
- Version: 20260127133341
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ruedaclubnz/ActiveSchedule
- Web: https://mule.run/skillshub/@@ruedaclubnz/ActiveSchedule~Debugging-Coach:20260127133341

---

---
name: Debugging-Coach
description: Structured, repeatable debugging methodology with automated analysis and metrics tracking
---

# Debugging-Coach Skill

## Overview
A systematic approach to debugging that produces artifacts, tracks metrics, and prevents recurring issues.

**Core Principles:**
1. **Iterative Refinement** — Max 3 attempts before escalating
2. **Chain-of-Thought** — Diagnose before fixing
3. **Minimal Changes** — Fix cause, not symptoms
4. **Checkpoint After Each Attempt** — Update SESSION_MEMORY.md

---

## Phase 0: Safety First (CRITICAL)

Before attempting complex fixes, create a restore point:
```powershell
.\tools\vc.ps1 Snap
```

If debugging leads to a dead end:
```powershell
.\tools\vc.ps1 Restore last
```

---

## Phase 1: Comprehend the Issue

### Error Classification
| Type | Examples | Typical Fix |
|------|----------|-------------|
| **Syntax Error** | Missing brackets, typos | IDE correction |
| **Type Error** | Wrong data types, casting | Type conversion |
| **Reference Error** | Missing imports, null | Add using/null check |
| **Logic Error** | Wrong behavior | Algorithm fix |
| **Runtime Error** | Crash during execution | Exception handling |

### Chain-of-Thought Questions
1. What is the exact error message?
2. What type of error is this?
3. When does it occur (startup, user action, async)?
4. Is it reproducible?

---

## Phase 2: Locate Suspect Code

1. Extract file path and line number from error
2. Use `view_file` to see ±20 lines context
3. Check related files (imports, dependencies)
4. Run caller analysis:
   ```powershell
   grep_search -Query "MethodName" -SearchPath "."
   ```

---

## Phase 3: Diagnose Root Cause

### Check Documentation First
1. `{MANUALS}\00_Governance\LESSONS_LEARNED.md`
2. `{MANUALS}\00_Governance\POTENTIAL_ISSUES.md`

### Common Revit/WPF Causes
| Error | Cause | Solution |
|-------|-------|----------|
| NullReferenceException | GetElement null | Add null check |
| InvalidOperationException | Wrong transaction | Check IsModifiable |
| InvalidObjectException | Deleted element | Validate exists |
| CrossThreadException | UI from background | Dispatcher.Invoke |

### 5 Whys Analysis
For complex bugs, trace causation chain:
1. Why did X fail? → Because Y was null
2. Why was Y null? → Because Z wasn't initialized
3. Why wasn't Z initialized? → Because async race condition
4. Why race condition? → No synchronization
5. **Root Cause:** Missing lock/await

---

## Phase 4: Propose Fix

- Make MINIMAL change
- Add defensive checks
- Include comment explaining fix:
  ```csharp
  // [FIX] Null check added - element may be deleted during iteration
  if (element == null) continue;
  ```

---

## Phase 5: Verify Fix

```powershell
.\tools\Verify-Project.ps1
```

**Checkpoint:** Update SESSION_MEMORY.md:
```markdown
## Debugging
- Attempt: [1|2|3]
- Error: [description]
- Fix tried: [what you did]
- Result: [passed|failed]
```

---

## Phase 6: Document (If Novel)

Add to `{MANUALS}\00_Governance\LESSONS_LEARNED.md`:
```markdown
### [Error Type]: [Brief Description]
**Symptom:** [What went wrong]
**Root Cause:** [5 Whys result]
**Solution:** [How fixed]
```

---

## Maximum Iteration Rules (CRITICAL)

| Iteration | Action |
|-----------|--------|
| 1 | Apply obvious fix |
| 2 | Research in LESSONS_LEARNED.md |
| 3 | **STOP — Escalate to user** |

**Escalation Format:**
```markdown
## ⚠️ Escalation Required

**Attempts:**
1. [What tried] → [Result]
2. [What tried] → [Result]
3. [What tried] → [Result]

**Persistent error:** [exact message]
**Question:** [specific ask for user]
```

---

## Tool Failure Recovery

If a tool fails (e.g., `replace_file_content` returns "target not found"):
1. **STOP** and analyze why
2. **DO NOT** retry blindly
3. **MANDATORY:** Call `view_file` to refresh context
4. Retry with updated parameters

---

## Rollback Protocol

If fix makes things worse:
```powershell
# List snapshots
.\tools\vc.ps1 List

# Restore last good state
.\tools\vc.ps1 Restore last
```

Or use `/rollback` workflow for structured recovery.

---

## Debug Report Template

After significant debugging sessions, create artifact:

```markdown
# Debug Report: [Issue]

## Error
[Exact error message]

## Root Cause
[5 Whys analysis result]

## Fix Applied
[Code change description]

## Verification
- Build: ✅/❌
- Tests: ✅/❌
- Manual: ✅/❌

## Prevention
[How to prevent recurrence]
```

---

## Metrics (Optional)

Track in `SESSION_MEMORY.md`:
- Debug sessions this week: X
- Average iterations: X
- Escalations: X
- Recurrent bugs: [list]