ultra-debug

What this skill does

# Ultra Debug

Orchestrate a team of debugger agents and a critic agent to investigate the root cause of a production issue through adversarial hypothesis testing.

## Input

The user provides: `$ARGUMENTS`

This may be a Sentry issue URL/ID, a problem description, relevant shop IDs, timestamps, error messages, or any combination.

## Orchestration Workflow

### Phase 0: Gather Context (keep it brief)

Spend minimal time here — just enough to frame the problem and form hypotheses. Quick searches are fine; deep investigation is the debuggers' job.

1. **Sentry**: If a Sentry URL or issue ID is provided, fetch the issue summary (title, stack trace, first/last seen)
2. **Quick checks**: A few log or code searches to understand the affected area are okay
3. **Summarize in one paragraph**: WHAT is broken, WHEN it started, WHO is affected, WHERE in the system

Do NOT spend more than a few tool calls here. Move on to hypothesis formation quickly.

### Phase 1: Form Hypotheses

Based on the summary and your general knowledge of the system, generate **5 distinct, testable hypotheses**. Each hypothesis must be:

- **Specific**: names a concrete mechanism (code path, data state, timing condition, external dependency)
- **Testable**: can be confirmed or refuted with available evidence (logs, code, data, errors)
- **Independent**: does not overlap significantly with other hypotheses

### Phase 2: Create Team

1. Create a team:

```
TeamCreate with team_name: "ultra-debug-<short-kebab-description>"
```

2. Create one task per hypothesis using TaskCreate:
   - Subject: `Investigate: <hypothesis summary>`
   - Description: full hypothesis details and suggested investigation approach

3. Create one task for the critic:
   - Subject: `Critique all hypotheses`
   - Description: list of all hypotheses, debugger names, and the evidence standards

### Phase 3: Spawn Agents

Spawn **all agents in parallel** (single message with multiple Agent tool calls).

For **each hypothesis**, spawn a debugger:

```
Agent tool:
  subagent_type: "debugger-teammate"
  team_name: "ultra-debug-<name>"
  name: "debugger-N"
  prompt: |
    You are debugger-N in team ultra-debug-<name>.

    YOUR HYPOTHESIS:
    <hypothesis description>

    PROBLEM CONTEXT:
    <gathered context from Phase 0>

    YOUR TEAMMATES:
    - Other debuggers: <list names and their hypotheses>
    - Critic: critic-1

    YOUR TASK ID: <task-id>

    Begin investigation. Share findings via SendMessage with critic-1
    and relevant debuggers.
```

Spawn **one critic**:

```
Agent tool:
  subagent_type: "critic-teammate"
  team_name: "ultra-debug-<name>"
  name: "critic-1"
  prompt: |
    You are critic-1 in team ultra-debug-<name>.

    PROBLEM CONTEXT:
    <gathered context from Phase 0>

    HYPOTHESES UNDER INVESTIGATION:
    1. <hypothesis 1> — investigated by debugger-1
    2. <hypothesis 2> — investigated by debugger-2
    3. <hypothesis 3> — investigated by debugger-3

    YOUR TASK ID: <task-id>

    Wait for debuggers to share initial findings, then begin your
    adversarial review. Continue for up to 5 rounds until every
    hypothesis is either proved or disproved.
```

### Phase 4: Monitor & Facilitate

1. **Wait** for agents to send findings — messages from teammates arrive automatically
2. If a debugger discovers evidence relevant to another's hypothesis, relay it if they haven't communicated directly
3. If agents are stuck (idle without progress), send guidance or additional context
4. Allow **up to 5 rounds** of challenge-response between debuggers and critic, until every hypothesis is either proved or disproved
5. If a new hypothesis emerges during investigation, spawn an additional debugger if warranted
6. Track progress via TaskList

### Phase 5: Synthesize Report

After all agents report their final assessments:

1. Collect all findings, evidence, and debate outcomes
2. Determine the consensus:
   - If one hypothesis **SURVIVED** the critic's challenges: status = **CONFIRMED**
   - If multiple survived or none did: status = **INCONCLUSIVE**
3. Write the report to `.claude-works/ultra-debug-<name>/report.md`
4. Present the report to the user

## Report Template

```markdown
# <title>

**Date**: YYYY-MM-DD
**Status**: CONFIRMED | INCONCLUSIVE

## Problem Statement

<What is broken. When it started. Who is affected. How it manifests.>

## Root Cause

<If CONFIRMED: Single definitive statement of the root cause, with primary evidence reference.>
<If INCONCLUSIVE: What was eliminated and what remains unresolved.>

## Evidence

| # | Finding | Source |
|---|---------|--------|
| 1 | <concrete finding> | <file:line / log timestamp / query / Sentry event ID> |
| 2 | ... | ... |

## Investigation Timeline

| Hypothesis | Verdict | Summary |
|------------|---------|---------|
| <hypothesis 1> | CONFIRMED / DISPROVED | <one line> |
| <hypothesis 2> | CONFIRMED / DISPROVED | <one line> |

## Debate Log

### Hypothesis 1: <name>
- **Debugger finding**: <summary with evidence refs>
- **Critic challenge**: <the challenge and its basis>
- **Resolution**: <how it was resolved, with evidence>

### Hypothesis 2: <name>
...

## Recommendations

<Concrete, actionable next steps based on findings. Reference specific code locations.>
```

## Strict Rules

### Language Rules

The final report MUST NOT contain any of these hedge words or phrases:

> likely, unlikely, maybe, perhaps, possibly, probably, might, could (expressing uncertainty),
> appears to, seems to, seems like, it looks like, we think, we believe,
> should be (expressing uncertainty), in theory

Every statement must be either:
- A **fact** backed by cited evidence in the Evidence table, OR
- Explicitly labeled as **[UNVERIFIED]** with a note on what evidence is missing

### Evidence Rules

- Code references: markdown link with `file:line` as link text and GitHub permalink with commit SHA as URL (e.g., `[/path/to/file.ts:142](https://github.com/org/repo/blob/<commit-sha>/path/to/file.ts#L142)`). Run `git rev-parse HEAD` to get the current commit SHA.
- Log references: timestamp and log source
- Database findings: the exact query used (reproducible)
- Sentry references: event ID or issue ID with link
- Git references: commit hash

### Scope Rules

- Do NOT fix the bug — only identify the root cause
- Do NOT modify any source files
- Do NOT speculate about fixes beyond the Recommendations section
- The report is the sole deliverable