claude-dev-env 1.21.1 → 1.22.0

package/skills/findbugs/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: findbugs
+description: >-
+  Audits the current branch's pull request as a whole for bugs by spawning the
+  code-quality-agent against the full PR diff with zero conversation context.
+  Returns P0/P1/P2 findings with file:line evidence and a verified-clean
+  coverage list. Read-only — never modifies code. Triggers: '/findbugs',
+  'find bugs in this PR', 'audit the PR', 'bug audit on the branch'.
+---
+
+# Findbugs
+
+**Core principle:** A clean-room bug audit on the entire pull request. The audit agent receives the PR diff and nothing else — no chat history, no prior framing, no implicit "we already looked at this." Independence is the point.
+
+## When this skill applies
+
+User types `/findbugs` or asks for a bug audit on the current branch's PR. Typical moment: PR is up (draft or ready), and the user wants an independent second pair of eyes before merge or before requesting human review.
+
+If the current branch has no associated PR and no diff against the default branch, say so and stop. Do not invent scope.
+
+## The Process
+
+### Step 1: Resolve PR scope
+
+Determine the audit target in this order:
+
+1. **Open PR for current branch.** Run `gh pr view --json number,baseRefName,headRefName,url` from the working directory. If a PR exists, capture its number, base ref, head ref, and URL.
+2. **No PR but a remote default branch exists.** Diff against the default branch's merge-base: `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`. Treat this as the audit scope.
+3. **Neither.** Respond exactly: `No PR or upstream diff found. Push the branch or open a PR first.` and stop.
+
+### Step 2: Capture the full PR diff
+
+When a PR exists: `gh pr diff <number> -R <owner>/<repo> > .findbugs-pr.patch`.
+
+When falling back to merge-base diff: `git diff <merge-base>...HEAD > .findbugs-pr.patch`.
+
+The audit's authoritative scope is this single diff file. Do not inject extra files, related history, or "files Claude edited this session" — those introduce anchoring bias.
+
+### Step 3: Spawn the code-quality-agent — clean room
+
+Call the Agent tool with:
+
+- `subagent_type: code-quality-agent`
+- `model: sonnet`
+- `description: "PR bug audit"`
+- `run_in_background: false` — the user invoked `/findbugs` to get a result on this turn
+
+**The agent prompt must be self-contained and context-free.** Specifically:
+
+- **No references to the orchestrator's conversation.** Forbidden phrases: "as we discussed," "the earlier issue," "given our prior work," "the bug from last turn," "you previously identified."
+- **No hints about expected outcomes.** Do not pre-stage findings, do not suggest where bugs probably are, do not name files as "the suspicious one." The agent forms its own hypotheses.
+- **No instructions to favor or skip particular categories** beyond the standard category list. No "skip the typing stuff" or "focus on the clipboard logic" — those bias the audit.
+- **Minimal background.** Identify the repo, branch, base branch, and PR URL only. Do not summarize what the PR does.
+
+The XML prompt skeleton:
+
+```xml
+<context>
+  <repo>owner/repo</repo>
+  <branch>head ref</branch>
+  <base_branch>base ref</base_branch>
+  <pr_url>url or "none"</pr_url>
+</context>
+
+<scope>
+  <diff_path>.findbugs-pr.patch (absolute path)</diff_path>
+  <scope_rule>Audit only lines added or modified in the diff. Pre-existing code on untouched lines is out of scope.</scope_rule>
+</scope>
+
+<bug_categories>
+  Investigate each explicitly:
+  A. API contract verification (signatures, return types, async/await correctness)
+  B. Selector / query / engine compatibility
+  C. Resource cleanup and lifecycle (file handles, connections, processes, locks)
+  D. Variable scoping, ordering, and unbound references
+  E. Dead code and unused imports
+  F. Silent failures (catch-all excepts, unconditional success returns, missing error propagation)
+  G. Off-by-one, bounds, and integer overflow
+  H. Security boundaries (injection, path traversal, auth bypass, secret leakage)
+  I. Concurrency hazards (race conditions, missing awaits, shared mutable state)
+  J. Magic values and configuration drift
+</bug_categories>
+
+<constraints>
+  Read-only. Report findings only. Do not modify code, do not propose
+  full diffs, do not commit, do not push. Cite file:line for every claim.
+  When the diff alone does not provide enough context to confirm or deny
+  a bug, list it under "Open questions" rather than asserting.
+</constraints>
+
+<output_format>
+  P0 = will not run / data corruption
+  P1 = regression or silent failure
+  P2 = dead code, minor smell
+
+  ## Summary
+  Total: N (P0=N, P1=N, P2=N)
+
+  ## Findings
+  ### [P_] short title
+  File: file/path:line
+  Category: A-J
+  Issue: 2-3 sentence description with concrete trace
+  Evidence: code excerpt or grep result
+
+  ## Verified clean
+  Per category investigated, name the evidence and the conclusion.
+
+  ## Open questions
+  Anything ambiguous from the diff alone.
+</output_format>
+```
+
+### Step 4: Surface findings, then clean up
+
+When the agent returns, report concisely:
+
+- One-line totals: `N P0 / N P1 / N P2 — K categories cleared`
+- Each finding's `file:line`, category, and one-sentence description
+- The cleared categories so the user can see coverage breadth
+- Any open questions the agent could not resolve from the diff alone
+
+Offer the next step without auto-executing it: `Want me to spawn clean-coder to fix the P0/P1 findings?`
+
+Delete `.findbugs-pr.patch` after the audit completes (or moves to a fix flow). Temporary diff files do not belong in the working tree.
+
+Do not paste the full agent transcript or the XML prompt unless the user asks.
+
+## Output Format
+
+```
+N P0 / N P1 / N P2 — K categories cleared
+
+P1 — short title
+  file/path.py:NN — one-sentence description (category: <name>)
+
+P2 — short title
+  file/path.py:NN — one-sentence description (category: <name>)
+
+Verified clean: <category>, <category>, <category>
+
+Open questions:
+  <if any>
+
+Want me to spawn clean-coder to fix the P0/P1 findings?
+```
+
+## Constraints
+
+- **Read-only.** The skill never edits code, never pushes, never commits.
+- **Foreground spawn.** The user is waiting for the result on this turn.
+- **PR-scoped, not session-scoped.** The audit covers the entire PR diff regardless of which files were edited in this conversation.
+- **Clean-room prompt.** The agent's prompt is self-contained — no references to chat history, no anchoring hints, no expected outcomes.
+- **No clean-coder auto-spawn.** Always ask before fixing.
+- **Trust the agent's verdict.** Pass through P0/P1/P2 categorizations as the agent assigned them; do not re-rank.
+- **Temp file cleanup.** Delete `.findbugs-pr.patch` when the audit ends.
+
+## Examples
+
+<example>
+User: `/findbugs`
+Claude: [resolves PR #42 from current branch, fetches full diff, spawns code-quality-agent foreground with self-contained prompt, returns]
+
+`1 P0 / 2 P1 / 0 P2 — 7 categories cleared`
+
+`P0 — race condition on shared cache write`
+`  src/cache.py:88 — concurrent writers can both pass the existence check before either writes (category: concurrency)`
+
+`P1 — silent paste failure`
+`  utils/clipboard.py:33 — validated_paste returns success without verifying the post-paste state (category: silent failure)`
+
+`P1 — unbound variable on early-exception path`
+`  src/processor.py:283 — scheduling_log referenced after try/finally where it may be unbound (category: scoping)`
+
+`Verified clean: API contract, selector compatibility, resource cleanup, dead code, off-by-one, security boundaries, magic values`
+
+`Open questions: none`
+
+`Want me to spawn clean-coder to fix the P0 + P1s?`
+</example>
+
+<example>
+User: `/findbugs`
+Claude: `No PR or upstream diff found. Push the branch or open a PR first.`
+</example>
+
+<example>
+User: `/findbugs` (branch with no PR but commits ahead of main)
+Claude: [falls back to `git diff origin/main...HEAD`, runs audit on that diff scope]
+</example>
+
+## Why this design
+
+Anchoring bias is the failure mode of context-rich audits. An agent that inherits "we just fixed three bugs in clipboard_utils.py" subconsciously scopes its hunt around clipboard_utils.py and pattern-matches on the same bug shapes. A clean-room audit on the full PR diff treats every file equally, considers every category, and surfaces things the orchestrator session never looked at. The diff is the contract; everything else is noise.

package/skills/fixbugs/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: fixbugs
+description: >-
+  Fixes the bugs surfaced by the most recent /findbugs invocation by handing
+  the findings to /agent-prompt, which authors a structured XML prompt and
+  spawns a background sonnet clean-coder agent to implement every fix in one
+  commit on the existing branch. Default scope: all severities. Optional
+  argument filters by severity (e.g. /fixbugs P0, /fixbugs P0+P1).
+  Triggers: '/fixbugs', 'fix all the bugs', 'apply the audit fixes',
+  'implement the findbugs results'.
+---
+
+# Fixbugs
+
+**Core principle:** A thin bridge between `/findbugs` (read-only audit) and `/agent-prompt` (structured prompt authoring + spawn). /fixbugs recovers the prior findings, packages them as a goal, and hands off. It does not author prompts itself, does not spawn agents directly, and does not run audits.
+
+## When this skill applies
+
+Right after `/findbugs` returned findings on the current branch and the user wants the bugs fixed without further triage. Bare `/fixbugs` defaults to all severities (P0 + P1 + P2). Argument-filtered invocations (e.g. `/fixbugs P0`, `/fixbugs P0+P1`, `/fixbugs P0 P1`) narrow the target set.
+
+Refusal cases:
+
+- **No findings in session.** Respond exactly: `No findings in this session. Run /findbugs first.` and stop.
+- **Most recent /findbugs returned zero bugs.** Respond exactly: `No bugs to fix.` and stop.
+- **Filter excludes every finding.** Respond: `No bugs match the filter <args>.` and stop.
+
+## The Process
+
+### Step 1: Recover the findings
+
+Locate the most recent `/findbugs` output in the current conversation. For each finding, capture:
+
+- Severity (`P0` / `P1` / `P2`)
+- `file:line`
+- Category (the A–J letter or category name `/findbugs` reported)
+- One-sentence description as `/findbugs` wrote it
+
+Apply the severity filter from `$ARGUMENTS` if present:
+
+- `P0` → P0 only
+- `P0+P1` or `P0 P1` → P0 and P1
+- `P1` → P1 only
+- absent → all severities
+
+If the filtered set is empty, refuse per the refusal cases above.
+
+### Step 2: Re-resolve PR scope
+
+Re-establish the same PR target `/findbugs` used:
+
+1. `gh pr view --json number,baseRefName,headRefName,url` from the working directory.
+2. Fall back to `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`.
+3. Neither → respond `No PR or upstream diff. Cannot scope fixes.` and stop.
+
+Capture: `<owner>/<repo>`, head branch, base branch, PR number, PR URL.
+
+### Step 3: Hand off to /agent-prompt
+
+Invoke the `agent-prompt` skill with a goal string of this exact shape:
+
+```
+Fix the following bugs surfaced by /findbugs on
+<owner>/<repo> @ <head_branch> (PR #<number>, base <base_branch>):
+
+[for each filtered finding, one bullet:]
+- [<severity>] <file:line> (<category>): <description>
+
+Deploy a clean-coder background agent (model: sonnet) to implement all fixes
+in one commit on the existing branch and push. Constraints:
+- Modify only the files referenced in the bug list above.
+- Do NOT change the PR base, do NOT rebase, do NOT amend, do NOT --force.
+- Do NOT skip git hooks (no --no-verify, no --no-gpg-sign).
+- Use git add by explicit path; never `git add .` or `git add -A`.
+- Preserve existing comments on lines you do not modify.
+- Type hints on every signature you touch.
+
+After push, report: commit SHA, per-file lines added/removed, hook output
+summary, and confirmation that each bug above was addressed.
+```
+
+`/agent-prompt` then runs its own workflow end-to-end: prompt-generator authoring, Outcome preview, AskUserQuestion confirmation gate, background spawn. The confirmation gate is preserved — fixes are write operations and the user must approve the final XML before the agent runs.
+
+### Step 4: Hand-off complete
+
+`/fixbugs` produces no further output. `/agent-prompt` owns the visible chat from this point: the XML fence, the Outcome digest, the AskUserQuestion, and the spawn confirmation. Do not duplicate any of those, do not summarize them, do not add commentary.
+
+## Output Format
+
+When `/fixbugs` proceeds, the visible output is `/agent-prompt`'s output — nothing from `/fixbugs` itself.
+
+When `/fixbugs` short-circuits (no findings, no PR, empty filter, zero bugs), the visible output is the single-line refusal message and nothing else.
+
+## Constraints
+
+- **Sequencing.** `/fixbugs` runs AFTER `/findbugs`. It does not perform audits.
+- **Scope inheritance.** Fixes target only files referenced in the prior `/findbugs` findings — the PR diff scope. Do not expand to unrelated files.
+- **No silent spawn.** `/agent-prompt`'s confirmation gate is preserved on every run.
+- **One commit per `/fixbugs` run.** All filtered fixes batch into a single commit.
+- **No `--force`, no `--amend`, no rebase, no base change.** Standard git workflow applies to the spawned agent.
+- **Sonnet for the implementer.** Always pass `model: sonnet` to the spawn — keeps cost predictable and matches the agent's training fit for code edits.
+- **Background spawn.** The user typed `/fixbugs` to delegate, not to wait. The agent runs in the background and notifies on completion.
+
+## Examples
+
+<example>
+User: `/findbugs` → returns `1 P0 / 2 P1 / 0 P2`
+User: `/fixbugs`
+Claude: [recovers all 3 findings, resolves PR scope, invokes /agent-prompt with a goal targeting all 3 bugs; /agent-prompt presents the XML + Outcome digest + AskUserQuestion; on Launch it, the background sonnet clean-coder spawns]
+</example>
+
+<example>
+User: `/findbugs` → returns `1 P0 / 2 P1 / 1 P2`
+User: `/fixbugs P0+P1`
+Claude: [filters to 3 findings (the P2 is dropped), hands the filtered set to /agent-prompt]
+</example>
+
+<example>
+User: `/fixbugs` (no prior /findbugs in session)
+Claude: `No findings in this session. Run /findbugs first.`
+</example>
+
+<example>
+User: `/findbugs` → returns `0 P0 / 0 P1 / 0 P2`
+User: `/fixbugs`
+Claude: `No bugs to fix.`
+</example>
+
+<example>
+User: `/findbugs` → returns `0 P0 / 0 P1 / 1 P2`
+User: `/fixbugs P0`
+Claude: `No bugs match the filter P0.`
+</example>
+
+## Why this design
+
+Three skills, three responsibilities:
+
+- `/findbugs` audits in a clean room, returns findings.
+- `/fixbugs` packages findings as a goal, delegates.
+- `/agent-prompt` authors the XML and spawns the agent (with confirmation).
+
+Each skill stays small and reuses what already exists. `/fixbugs` adds value by recovering findings from chat, filtering by severity, and writing the goal in `/agent-prompt`'s expected shape — not by reimplementing prompt authoring or spawn logic. The `/agent-prompt` confirmation gate is non-negotiable because fixes write code, push to a PR, and are visible to reviewers; the friction is the safety.