Diagnose

---
name: diagnose
description: Analyze a bug from error logs or reproduction steps, fix it, and create a GH Issue + PR.
argument-hint: '[error description or file path]'
disable-model-invocation: false
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — diagnose

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.

### Checkpoint Verification Pattern
Every phase has a checkpoint. Run the verification command and check the exit code.
- Exit non-zero (blocking gate): **STOP immediately**, report failure, do NOT proceed.
- Exit 0 with an `ADVISORY:` line (advisory gate): report the gap, self-correct, continue.
Standard prefix:
```
bash scripts/checkpoint.sh
```
Append `--skill <name> --phase <phase> --issue <ID>` for the specific check.
`checkpoint.sh` resolves the main repo root internally, so the command stays
a single prefix-matchable form (safe to allowlist as `Bash(bash scripts/checkpoint.sh *)`).

### Worktree Setup Pattern
Pipeline skills operate in git worktrees to isolate changes from main.
- Create + freeze: `WT="$(bash scripts/wt_setup.sh <branch>)"` — creates the
  worktree via `scripts/worktree.sh create` and writes `.claude-kit/freeze-dir.txt`
  inside it in a single step.
- Resolve main root: `bash scripts/worktree.sh root`
- Remove safely: `bash scripts/wt_cleanup.sh <branch>` — cd's to main root
  inside a subshell, then removes the worktree (never leaves CWD dangling).
All file operations happen inside `$WT/`. Shared files live on main only.

### Registry Update Pattern
Shared files (`issues.md`, `STATUS.md`, `CHANGELOG.md`) are managed on main only.
Always use `registry_edit.sh` for concurrent-safe writes — it resolves the
main repo root internally and delegates to `flock_edit.sh`:
```bash
bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'
```
Never commit these files to feature branches.
## Checkpoint Rules — MANDATORY
Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. Blocking gates exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates always exit 0 and print an `ADVISORY:` line on failure: report the gap, self-correct, then continue (ISSUE-031). Never skip running either tier.

**Slug convention**: After creating the worktree, store the branch slug (e.g., `fix/bookmark-none-subscript`) for use in checkpoint commands.

## Argument Validation (run before anything else)
1) If `$ARGUMENTS` is empty or blank, ask the user: "Please provide an error description, stack trace, or file path to diagnose."
2) Do NOT proceed until the user provides diagnostic context.

Steps:
1) Ensure `gh` authenticated (`gh auth status`).
2) Gather the bug context from $ARGUMENTS (error message, stack trace, file path, or reproduction steps).
3) If a file path is provided, read it. If an error message is provided, use Grep to locate the source.
4) Trace the execution path from the error backward to identify the root cause.
5) Form 1–3 ranked hypotheses and verify each by reading relevant code.
6) Present the confirmed root cause and a minimal fix to the user.
7) After user approval, apply the fix.
8) Run `pytest` to confirm no regressions. Suggest a regression test if none exists.
9) Create worktree + auto-freeze in one step:
   ```bash
   WT="$(bash scripts/wt_setup.sh fix/<slug>)"
   ```
   `wt_setup.sh` creates the worktree and writes the freeze marker inside
   `.claude-kit/freeze-dir.txt` atomically. Apply the fix inside `$WT/`,
   run tests from `$WT/`.

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill diagnose --phase worktree --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill diagnose --phase test --issue "$SLUG"`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

10) Create GH Issue:
    - `gh issue create --title "fix: <concise bug description>" --body "<body>"`
    - Body must include: error summary, root cause analysis, fix description, and affected files.
11) Commit + push (from `$WT/`).

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill diagnose --phase push --issue "$SLUG"`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

12) Create PR:
    - `gh pr create --title "fix: <concise bug description>" --body "Closes #<issue_number>\n\n<details>"`
13) Report the PR URL to the user — continue with `/review` and `/ship`.

## Sprint Integration (optional)
If `issues.md` exists in the project root, register this work in the sprint ecosystem:
1) Read `issues.md` to find the next available ISSUE-NNN number.
2) Append a new issue entry via the registry wrapper:
   ```bash
   bash scripts/registry_edit.sh issues.md -- bash -c '<append issue entry>'
   ```
   Issue fields:
   - Title: same as GH Issue title
   - Track: platform
   - Priority: P2
   - Status: done (PR already created)
   - GH-Issue: `<number>`
   - PR: `<pr_url>`
   - Depends-On: none
3) This allows team-lead to track standalone skill work in sprint_state.md.

If `issues.md` does not exist, skip this step silently.

## Error Handling
- If `gh auth status` fails: stop and instruct the user to run `gh auth login`.
- If the error cannot be located in the codebase: ask the user for more context (full stack trace, reproduction steps).
- If multiple root causes are plausible: present all hypotheses ranked by likelihood and ask the user to help narrow down.
- If tests fail after fix: do NOT push or create PR. Report failing tests and stop.

## Rollback
- Use `bash scripts/wt_cleanup.sh <branch>` for safe worktree removal —
  the wrapper cd's to main root and removes the worktree in a single subshell.
- If failure occurs after worktree creation but before PR:
  1. `bash scripts/wt_cleanup.sh <branch>`
  2. `git push origin --delete <branch>` (remote cleanup, if pushed)
- If failure occurs after PR creation: `gh pr close <pr_number>` then clean up worktree and branch as above.

## Shared Registry Files
**IMPORTANT**: Never commit `issues.md`, `STATUS.md`, or `CHANGELOG.md` to the feature branch.
These are registry files managed only on main. Always use `bash scripts/registry_edit.sh <file> -- bash -c '<update command>'` — the wrapper resolves the main repo root internally.

## Guidelines
- Never guess-and-patch. Always confirm the root cause before proposing a fix.
- One bug per PR. Keep fixes minimal — do not refactor surrounding code or fix unrelated bugs in the same change.
- Always write a regression test that fails before the fix and passes after. Never "fix" by suppressing errors (bare `except`, empty `catch`).
- Present hypotheses ranked by likelihood — let the user help narrow down if needed.
- Document the chain of causation in the GH Issue body for future reference.