Kit Preamble — 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(bash scripts/kit_update_check.py ), Bash(python3 scripts/), Bash(git *), Bash(gh *), Bash(pytest *), Bash(npm *)

Kit Preamble — diagnose

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Checkpoint Verification Pattern

Every phase has a mandatory checkpoint. Run the verification command and check exit code. If exit code is not 0, STOP immediately and report failure. Do NOT proceed to the next phase. 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.

Self-Review Requirements

Before completing any major phase, pause and verify:

• Does the output satisfy the stated acceptance criteria?
• Are there edge cases not covered?
• Could this break existing functionality?
• Rate confidence: High / Medium / Low. If Low, flag to the user before proceeding.

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

Checkpoint Rules — MANDATORY

Every phase in this skill that has a CHECKPOINT block must be verified. Run the verification command after completing each phase. If the exit code is not 0, STOP immediately and report the failure. Do NOT proceed to the next phase.

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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill diagnose --phase worktree --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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 — MANDATORY — NEVER SKIP Run: bash scripts/checkpoint.sh --skill diagnose --phase push --issue "$SLUG" If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

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.