lvlup-sw/debug

Debug Workflow Skill

Overview

Investigation-first workflow for debugging and regression fixes. Provides two tracks based on urgency: hotfix (fast, minimal ceremony) and thorough (rigorous, full RCA documentation).

Triggers

Activate this skill when:

• User runs debug command
• User reports a bug or regression
• User needs to investigate an error
• User says "fix this bug" or similar

Disambiguation: If the user says "fix" or "clean up" — use debug when something is broken (error, crash, wrong behavior). Use refactor when the code works but needs structural improvement.

Workflow Overview

                              debug
                                 │
                            ┌────┴────┐
                            │ Triage  │
                            └────┬────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                 │
          --hotfix            (default)       --escalate
               │                 │                 │
               ▼                 ▼                 ▼
      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
      │  Hotfix Track  │  │   Thorough  │   │ ideate  │
      │                │  │    Track    │   │ handoff  │
      └────────────────┘  └─────────────┘   └──────────┘

Command Interface

Start Debug Workflow

# Default: thorough track
debug "Description of the bug"

# Fast path: hotfix track
debug --hotfix "Production is down - users can't login"

# Escalate to feature workflow
debug --escalate "This needs architectural changes"

Mid-Workflow Commands

# Switch from hotfix to thorough (during investigation)
debug --switch-thorough

# Escalate to ideate (manual handoff)
debug --escalate "Reason for escalation"

# Resume after context compaction
rehydrate <featureId>

Track Comparison

| Aspect | Hotfix | Thorough | |--------|--------|----------| | Urgency | P0 (production down) | P1/P2 (normal priority) | | Investigation | 15 min time-boxed | No time limit | | RCA Document | No (minimal in state) | Yes (full docs/rca/) | | Worktree | No (in-place fix) | Yes (isolated) | | Review | Smoke test only | Spec review | | Human Checkpoints | 1 (merge) | 1 (merge) |

Decision Runbooks

For track-selection criteria at the triage phase, query the decision runbook: exarchos_orchestrate({ action: "runbook", id: "triage-decision" })

For investigation escalation criteria, query: exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })

These runbooks encode the structured decision trees for track selection. The agent reads the decision tree and follows the guidance — the platform does not execute branches.

When to use debug vs refactor

| Signal | Use debug | Use refactor | |--------|-----------|--------------| | Something is broken or wrong | Yes | No | | Code works but is messy/complex | No | Yes | | Users report a bug or regression | Yes | No | | Performance degradation | Start with debug (investigate) | Escalate to refactor if structural | | "This should be reorganized" | No | Yes | | Error in production logs | Yes | No |

Rule of thumb: if there is a symptom (something that should work but doesn't), use debug. If there is dissatisfaction with working code (hard to read, violates SOLID, duplicated logic), use refactor.

Hotfix Track

Fix production issues ASAP. Speed over ceremony.

HSM phases: triage → investigate (15 min max) → hotfix-implement (no worktree) → hotfix-validate → completed

See references/triage-questions.md for triage guidance.

Investigation Timer

1. On hotfix track selection: record investigation.startedAt in state
2. After each major finding: check elapsed time
3. At 15 min mark: emit investigation.timeout event, pause for user confirmation
   • Switch to thorough track? (yes/no)

For detailed phase instructions, see references/hotfix-track.md.

Thorough Track

Fix bugs with proper rigor. Full RCA documentation.

HSM phases: triage → investigate → rca → design → debug-implement (worktree + TDD) → debug-validate → debug-review → synthesize → completed

For detailed phase instructions, see references/thorough-track.md. For systematic investigation methodology, see references/investigation-checklist.md.

Design-time Constraints (Thorough Track: rca + design phases)

The rca and design phases are the thorough track's design-time surfaces. At these phases — before committing to a fix approach — surface a Constraints section anchored to the architectural invariants relevant to the fix. This is the debug design-time equivalent of /ideate's Phase 0 and uses the same single shared source of truth for the selection rules and devCatalog gating: see @skills/ideate/references/constraint-anchoring.md. Load .exarchos/invariants.md (cost-of-load: always-load entries) and emit the Constraints section. devCatalog-gated: when .exarchos.yml: invariants.devCatalog: enabled is unset or disabled, surface no Constraints section and proceed directly. The hotfix track skips this step (speed over ceremony).

Characterization Testing (Thorough Track Only)

Before fixing a bug in the thorough track, capture the buggy behavior as a characterization test:

1. Before fix: Write a test that documents the current (buggy) behavior — it should PASS with the bug present
2. Write the fix test: Write a test that describes the correct behavior — it should FAIL (this is the standard TDD RED phase)
3. Apply the fix: Implement the fix. The fix test should now PASS, and the characterization test should now FAIL
4. Verify: The characterization test failing confirms the bug is actually fixed. If it still passes, the fix didn't address the root cause.

This is not required for the hotfix track — hotfixes prioritize speed over documentation.

Track Switching

• Hotfix -> Thorough: When investigation timer expires (15 min). All findings preserved.
• Thorough -> Escalate: When fix requires architectural changes. Hand off to ideate.

For detailed switching logic, see references/thorough-track.md.

Auto-Chain Behavior

Both tracks have ONE human checkpoint before completion.

Hotfix auto-chain:

triage → investigate → hotfix-implement → [HUMAN: hotfix-validate] → completed
         (auto)        (auto)

Thorough auto-chain:

triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [HUMAN: synthesize] → completed
         (auto)        (auto) (auto)   (auto)           (auto)            (auto)

State Management

Initialize debug workflow:

action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"

See @skills/debug/references/state-schema.md for full schema.

Phase Transitions and Guards

Every phase transition has a guard that must be satisfied. Before transitioning, consult @skills/checkpoint/references/phase-transitions.md for the exact prerequisite for each guard.

Schema Discovery

Use exarchos_workflow({ action: "describe", actions: ["update", "init"] }) for parameter schemas and exarchos_workflow({ action: "describe", playbook: "debug" }) for phase transitions, guards, and playbook guidance.

Integration Points

With rehydrate

Debug workflows resume like feature workflows:

rehydrate <featureId>

With Existing Skills

• Uses spec-review skill for thorough track review phase
• Uses synthesis skill for PR creation
• Uses git-worktrees skill for thorough track implementation

With MCP Workflow State Tools

Extended to support:

• workflowType: "debug" field
• Debug-specific phases surfaced by rehydrate <featureId> (the rehydration document's next_actions envelope determines the next verb on resume)
• Debug context surfaced via rehydrate <featureId> at session start (no implicit hook)

Completion Criteria

Hotfix Complete

• [ ] Root cause identified (even if briefly)
• [ ] Minimal fix applied
• [ ] Affected tests pass
• [ ] Follow-up RCA task created
• [ ] Changes merged

Completion guard shapes — set these via exarchos_workflow update before transitioning to completed:

| Exit path | Guard | Required state | |-----------|-------|----------------| | Direct push (no PR) | fix-verified-directly | resolution: { directPush: true, commitSha: "<sha>" } | | Validation passed | validation-passed | validation: { passed: true } | | Via PR | Through synthesize → completed | prUrl must exist |

Thorough Complete

• [ ] Full RCA documented in docs/rca/ (use references/rca-template.md)
• [ ] Fix matches RCA findings
• [ ] TDD implementation with tests
• [ ] Spec review passed
• [ ] PR merged

Completion guard shapes — the thorough track exits through synthesize → completed (guard: pr-url-exists, requires prUrl in state).

Anti-Patterns

| Don't | Do Instead | |-------|------------| | Start coding before understanding bug | Investigate first, always | | Skip RCA on thorough track | Document for future learning | | Exceed 15 min on hotfix investigation | Switch to thorough track | | Add features during bug fix | Scope creep - only fix the bug | | Skip tests because "it's just a fix" | Fixes need tests to prevent regression |

Troubleshooting

See references/troubleshooting.md for MCP tool failures, state desync, investigation timeouts, and track switching issues.