debug

What this skill does

# 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 `/exarchos: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 `/exarchos:debug` when something is *broken* (error, crash, wrong behavior). Use `/exarchos:refactor` when the code *works* but needs structural improvement.

## Workflow Overview

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

## Command Interface

### Start Debug Workflow

```bash
# Default: thorough track
/exarchos:debug "Description of the bug"

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

# Escalate to feature workflow
/exarchos:debug --escalate "This needs architectural changes"
```

### Mid-Workflow Commands

```bash
# Switch from hotfix to thorough (during investigation)
/exarchos:debug --switch-thorough

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

# Resume after context compaction
/exarchos: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.

## 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/brainstorming/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 `/exarchos: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/workflow-state/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 /exarchos:rehydrate

Debug workflows resume like feature workflows:
```bash
/exarchos: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 `/exarchos:rehydrate <featureId>` (the rehydration document's `next_actions` envelope determines the next verb on resume)
- Debug context surfaced via `/exarchos: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, com