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/*)

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 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. 5.5) Self-Review (MANDATORY):
   • Re-read the root cause hypothesis and the proposed fix.
   • Trace backward from the fix: does it address the root cause, or just a symptom?
   • Actively search for evidence that contradicts the hypothesis.
   • Check all callers/consumers of the modified code for unintended side effects.
   • List 3+ edge cases and verify the fix handles them.
   • Rate confidence (High/Medium/Low).
     • Low → gather more info, do NOT proceed.
     • Medium → present uncertainty to user with specific questions.
     • High → proceed to step 6.
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:

   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 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.
• Keep fixes minimal — do not refactor surrounding code.
• Always write a regression test that fails before the fix and passes after.
• 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.

Execution Principles (absorbed from the diagnostician persona — ISSUE-034)

• Trace backward from the error to the root cause before proposing any fix — symptom suppression creates new bugs.
• One bug per PR; do not refactor surrounding code or fix unrelated bugs in the same change.
• Write a regression test that fails before the fix and passes after. Never "fix" by suppressing errors (bare except, empty catch).
• If multiple causes are possible, present them ranked by likelihood and ask before applying a fix. Document the causation chain in the issue body.