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 catalog-registration gating: see @skills/ideate/references/constraint-anchoring.md. Load .exarchos/invariants.md (cost-of-load: always-load entries) and emit the Constraints section. Catalog-registration gated: when no catalog is registered under .exarchos.yml: invariants.catalogs, 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.