kha-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

<objective>
Debug issues using scientific method with subagent isolation.

**Orchestrator role:** Gather symptoms, spawn kha-debugger agent, handle checkpoints, and keep each diagnosis or fix attempt isolated.

**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
</objective>

## Modes

### Default: diagnose-only (no mutation)
- Reads logs, traces, recent commits, runs read-only tools.
- Output: `.planning/debug/<session>/HYPOTHESIS.md` with prioritized
  hypotheses and the evidence for each.
- Side effects: NONE on user code. NONE on .planning state beyond the
  HYPOTHESIS.md write.

### Opt-in: --fix mode
- After diagnose-only run, user reviews HYPOTHESIS.md and explicitly
  invokes with `--fix --hypothesis-id <id>` to attempt the chosen fix.
- Single-hypothesis fix per invocation (no batch).
- Atomic commit per fix attempt; revertable.

### Opt-in: --interactive mode
- Walk through hypotheses one at a time, ask user to accept/reject each.
- Same single-fix-per-acceptance contract as --fix.

## Why default-diagnose-only

- Bug analysis benefits from human review before code changes
- Premature mutation may mask the actual root cause
- Atomic per-fix invocation gives clean git history for each attempt

## Stability

- `--fix` mode follows the standard atomic-commit-per-mutation contract and is rollback-friendly.

<available_agent_types>
Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
- kha-debugger - Diagnoses issues and can apply a single hypothesis-scoped fix when explicitly instructed
</available_agent_types>

<context>
User's issue: $ARGUMENTS

Parse flags from $ARGUMENTS:
- Default to `mode=diagnose`.
- If `--fix` is present, require `--hypothesis-id <id>`, set `mode=fix`, and remove both from the issue description.
- If `--interactive` is present, set `mode=interactive` and remove the flag from the issue description.
- Reject `--fix` combined with `--interactive`.
- Reject `--hypothesis-id` unless `--fix` is present.

Check for active sessions:
```bash
ls .planning/debug/*/HYPOTHESIS.md 2>/dev/null | head -5
```
</context>

<process>

## 0. Initialize Context

```bash
INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

Extract `commit_docs` from init JSON. Resolve debugger model:
```bash
debugger_model=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" resolve-model kha-debugger --raw)
```

## 1. Check Active Sessions

If active sessions exist AND no issue description AND `mode=diagnose`:
- List sessions with status, top hypotheses, and next action
- User picks number to resume OR describes new issue

If `mode=fix` or `mode=interactive`:
- Resolve the target session from the issue description if supplied; otherwise use the most recent unresolved session and ask the user to confirm if multiple candidates exist
- Require `.planning/debug/{session}/HYPOTHESIS.md`
- Refuse to continue if no hypothesis report exists for the selected session

If issue description is provided OR user describes a new issue:
- Continue to symptom gathering for diagnose mode
- Continue to hypothesis review for fix or interactive mode

## 2. Gather Symptoms (diagnose mode only)

Use AskUserQuestion for each:

1. **Expected behavior** - What should happen?
2. **Actual behavior** - What happens instead?
3. **Error messages** - Any errors? (paste or describe)
4. **Timeline** - When did this start? Ever worked?
5. **Reproduction** - How do you trigger it?

After all gathered, confirm ready to investigate.

## 3. Spawn kha-debugger Agent

### Diagnose-only mode

Fill prompt and spawn:

```markdown
<objective>
Investigate issue: {session}

**Summary:** {trigger}
</objective>

<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>

From trevi00/khaness, MIT.

More from trevi00/khaness