claude-dev-env 1.93.1 → 1.94.0

package/skills/findbugs/CLAUDE.md

@@ -1,20 +0,0 @@
-# findbugs
-
-Audits the current branch's pull request for bugs by spawning the `code-quality-agent` against the full PR diff in a clean room. Triggered by `/findbugs`, `find bugs in this PR`, `audit the PR`, or `bug audit on the branch`.
-
-## Purpose
-
-Read-only. The skill resolves PR scope via the `pr-scope-resolve` skill, writes the diff to a scoped temp file, and spawns two `code-quality-agent` instances (primary sonnet + secondary haiku) with a self-contained, context-free prompt covering all A–P audit categories. After both return it merges findings (de-dup, max-wins severity), posts one audit review to the PR via the `post-audit-findings` skill (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty), and reports totals and cleared categories to the user.
-
-## Key file
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Five-step process: resolve scope (`pr-scope-resolve` skill), capture diff to a scoped temp path, spawn agents (clean-room prompt XML), post audit review (`post-audit-findings` skill), surface findings and offer `/fixbugs`. Includes refusals and the output format. |
-
-## Constraints
-
-- Never edits files, never commits, never pushes.
-- One audit review per invocation is posted back to the PR — required so the unresolved-thread gate sees the audit pass.
-- Disabled by `CLAUDE_REVIEWS_DISABLED=bugteam` (shared token across the audit-skill family).
-- Always ask before running `/fixbugs`; never auto-spawn the fixer.

package/skills/findbugs/SKILL.md

@@ -1,241 +0,0 @@
----
-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.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix.
-
-## 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.
-
-## Refusals
-
-First match wins; respond with the quoted line exactly and stop:
-
-- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` carries the
-  token `bugteam`:
-  `/findbugs is disabled via CLAUDE_REVIEWS_DISABLED.` Run the check via
-  `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugteam`
-  (exit 0 = disabled). `/findbugs` is a PR bug-audit skill in the same family
-  as `/bugteam` and `/qbug`, so the shared `bugteam` token disables all three.
-  The gate semantics live in the `reviewer-gates` skill (`../reviewer-gates/SKILL.md`).
-
-## The Process
-
-### Step 1: Resolve PR scope
-
-Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `findbugs`. Findbugs consumes the resolved `owner`, `repo`, `number`, `head_ref`, `base_ref`, and `url`; when no PR exists, the ladder's merge-base rung sets the audit scope. When no target exists, respond exactly with the sub-skill's canonical refusal line and stop:
-
-`No PR or upstream diff. /findbugs needs a target.`
-
-### Step 2: Capture the full PR diff
-
-Resolve the temp diff path **once, Claude-side**, before invoking any shell command. Use Python's `tempfile.gettempdir()` which honors `TMPDIR`, `TEMP`, and `TMP` in the platform-correct order and falls back to `C:\Users\<user>\AppData\Local\Temp` on Windows or `/tmp` on Unix. Avoid hand-rolled env var chains. The lookup works on macOS, Linux, Windows cmd.exe, and PowerShell:
-
-```
-import tempfile
-diff_temp_path = Path(tempfile.gettempdir()) / f"findbugs-pr-{os.getpid()}.patch"
-```
-
-`os.getpid()` supplies the per-invocation suffix that prevents collisions with parallel `/findbugs` runs (a UUID or timestamp is equally acceptable). Capture the resolved absolute path as `<diff_temp_path>` and pass that **literal** path to every shell command that follows. Shell-side parameter expansion (`${TMPDIR:-/tmp}`, `$$`, `%TEMP%`) is forbidden because cmd.exe and PowerShell do not honor it.
-
-When a PR exists: call `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` and save the returned diff content to `"<diff_temp_path>"`.
-
-When falling back to merge-base diff: `git diff <merge-base>...HEAD > "<diff_temp_path>"`.
-
-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 twice in a single message (primary + Haiku secondary per the audit contract's Haiku secondary section):
-
-- Primary: `subagent_type: code-quality-agent`, `model: sonnet`, `description: "PR bug audit"`, `run_in_background: false`
-- Secondary: `subagent_type: code-quality-agent`, `model: haiku`, `description: "PR bug audit (secondary)"`, `run_in_background: false`
-
-After both return, merge per the contract's Haiku secondary section (de-dup key, max-wins severity, malformed-output fallback) before reporting to the user.
-
-**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><diff_temp_path> (absolute scoped temp path from Step 2)</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
-  B. Selector / query / engine compatibility
-  C. Resource cleanup and lifecycle
-  D. Variable scoping, ordering, and unbound references
-  E. Dead code and unused imports
-  F. Silent failures
-  G. Off-by-one, bounds, integer overflow
-  H. Security boundaries
-  I. Concurrency hazards
-  J. CODE_RULES.md compliance
-  K. Codebase conflicts (incomplete propagation)
-  L. Behavior-equivalence for refactors
-  M. Producer/consumer cardinality vs collection-type contract
-  N. Test-name scenario verifier
-  O. Docstring / fixture-prose vs implementation drift
-  P. Name / regex / word-list vs behavior-contract precision
-
-  The category list above is a summary. The binding definition of each
-  category is its rubric file under $HOME/.claude/audit-rubrics/category_rubrics/
-  (ready-to-send prompt variants under $HOME/.claude/audit-rubrics/prompts/).
-  Read the rubric files before auditing.
-</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>
-  Follow the shared audit contract at $HOME/.claude/_shared/pr-loop/audit-contract.md:
-
-  - Severity: P0 = will not run / data corruption; P1 = regression or silent
-    failure; P2 = dead code, minor smell.
-  - Per category, produce either Shape A (structured finding) or Shape B
-    (proof-of-absence). Bare "verified clean" labels are REJECTED.
-  - Run the contract's adversarial second pass after the primary list.
-
-  Preamble: `Total: N (P0=N, P1=N, P2=N)`. Emit findings and proof-of-absence
-  entries in the JSON shapes defined by the contract. Include an "Open
-  questions" section for items the diff alone cannot resolve.
-</output_format>
-```
-
-### Step 4: Post the audit review
-
-Every `/findbugs` invocation posts one audit review back to the PR. The
-unresolved-thread gate counts review threads, so a findbugs pass that
-returns findings without posting them as inline comments is invisible
-to the gate. Findbugs remains read-only on code — the review post is
-the only side effect.
-
-Capture `<head_sha>` once at the start of Step 4 via `git rev-parse
-HEAD` in the worktree the diff was scoped against.
-
-After the agent (and Haiku secondary) return and the merge is complete,
-apply the `post-audit-findings` skill (`../post-audit-findings/SKILL.md`)
-with `--skill findbugs`. That skill owns the findings-JSON mapping, the
-anchored-only serialization (unanchored findings surface via Step 5's
-user-facing output), the CLEAN/DIRTY decision, the self-PR reviewer
-toggle, and the exit codes. On exit 0, surface the emitted review
-`html_url` alongside the totals in Step 5. On exit 2, tell the user the
-review post failed and that the unresolved-thread gate will not see this
-audit pass; do not retry silently.
-
-### Step 5: 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 run /fixbugs for the P0/P1 findings?`
-
-Delete the scoped temp diff at `<diff_temp_path>` 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 run /fixbugs for the P0/P1 findings?
-```
-
-## Constraints
-
-- **Read-only on code.** The skill never edits files, never pushes, never commits. One audit review per invocation gets posted back to the PR (Step 4) — that is the only side effect, and it is required so the unresolved-thread gate sees the audit pass.
-- **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 the scoped `<diff_temp_path>` 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 — 11 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: I — Concurrency hazards)`
-
-`P1 — silent paste failure`
-`  utils/clipboard.py:33 — validated_paste returns success without verifying the post-paste state (category: F — Silent failures)`
-
-`P1 — unbound variable on early-exception path`
-`  src/processor.py:283 — scheduling_log referenced after try/finally where it may be unbound (category: D — Variable scoping, ordering, and unbound references)`
-
-`Verified clean: API contract, selector compatibility, resource cleanup, dead code, off-by-one, security boundaries, CODE_RULES.md compliance, codebase conflicts, behavior-equivalence, producer/consumer cardinality, Test-name scenario verifier`
-
-`Open questions: none`
-
-`Want me to run /fixbugs for the P0 + P1s?`
-</example>
-
-<example>
-User: `/findbugs`
-Claude: `No PR or upstream diff. /findbugs needs a target.`
-</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/CLAUDE.md

@@ -1,19 +0,0 @@
-# fixbugs
-
-Bridges `/findbugs` audit results to `/agent-prompt` for automated fixing. Triggered by `/fixbugs`, `fix all the bugs`, `apply the audit fixes`, or `implement the findbugs results`.
-
-## Purpose
-
-A thin bridge: recover the prior `/findbugs` findings from the current conversation, apply an optional severity filter (`P0`, `P0+P1`, `P1`, or all), re-resolve PR scope, then hand the filtered finding list to `/agent-prompt` as a structured goal string. `/agent-prompt` authors the XML prompt, shows an Outcome preview, asks for confirmation, and spawns a background sonnet `clean-coder` agent to apply all fixes in one commit.
-
-This skill never audits, never edits files, and never spawns agents directly. The `/agent-prompt` confirmation gate is always preserved.
-
-## Key file
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Four-step process: recover findings, apply severity filter, re-resolve PR scope, hand off to `/agent-prompt` with a goal string in the exact expected shape. Includes refusal cases (no findings, zero bugs, empty filter, missing `agent-prompt` skill) and the implementer constraints (one commit, no `--force`, no rebase, explicit `git add` by path). |
-
-## Invocation order
-
-Run `/findbugs` first, then `/fixbugs`. Running `/fixbugs` with no prior `/findbugs` in the session returns `No findings in this session. Run /findbugs first.`

package/skills/fixbugs/SKILL.md

@@ -1,142 +0,0 @@
----
-name: fixbugs
-description: >-
-  Fixes the bugs from the latest /findbugs run by handing them to /agent-prompt,
-  which spawns a background agent to apply every fix in one commit. An optional
-  argument filters by severity (e.g. /fixbugs P0). Triggers: '/fixbugs', 'fix
-  all the bugs', 'apply the audit fixes', 'apply 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.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the goal string handed to `/agent-prompt` so the spawned fix agent inherits it.
-
-## 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.
-- **Agent-prompt skill not installed.** Before Step 1, verify the `agent-prompt` skill is in the available skills list. If missing, respond: `agent-prompt skill not installed. /fixbugs hands off to it; install it first.` 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–P 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
-
-Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `fixbugs` to resolve the same PR target `/findbugs` used — the fixes stay scoped to the files the `/findbugs` findings from Step 1 name. When no target exists, respond with the sub-skill's canonical refusal line and stop:
-
-`No PR or upstream diff. /fixbugs needs a target.`
-
-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 background implementer (model: sonnet) to implement all fixes
-in one commit on the existing branch and push. The implementer must **Read** the clean-coder agent file first (`~/.claude/agents/clean-coder.md`; Windows `%USERPROFILE%\.claude\agents\clean-coder.md`) and treat it as binding; on Cursor use `Task` + `generalPurpose` with that Read in the prompt when `clean-coder` is not a valid `Task` subtype. 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 implementer 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.

package/skills/gh-paginate/CLAUDE.md

@@ -1,18 +0,0 @@
-# gh-paginate skill
-
-Provides the safe-pagination rule and patterns for `gh api` calls against paginated GitHub list endpoints (PR reviews, PR comments, issue comments, pulls, issues). The rule prevents two silent-truncation defects: default page truncation and per-page `--jq` evaluation.
-
-**Trigger:** Loaded by the `gh-paginate` skill name or when any skill or rule references the pagination rule.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete rule: affected endpoints, safe `--paginate --slurp \| jq` pattern, single-page bound pattern, single-object pattern, newest-first walk pattern, and enforcement notes |
-
-## Conventions
-
-- The preferred pattern pipes `--paginate --slurp` to an **external** `jq` invocation so cross-page operations (`sort_by`, `last`, `reverse`) run on the merged array-of-pages. The built-in `--jq` flag is incompatible with `--slurp` and runs per-page, producing wrong cross-page results.
-- Single-object endpoints (e.g., `pulls/<number>`) are not paginated; `--paginate` is unnecessary and `gh --jq` is safe.
-- The single-page bound pattern (`?per_page=100` without `--paginate`) is acceptable only when the list is confirmed to stay under 100 entries.
-- This skill ships as documentation only; enforcement via a future PreToolUse hook is noted in `SKILL.md`.

package/skills/gh-paginate/SKILL.md

@@ -1,84 +0,0 @@
----
-name: gh-paginate
-description: Safe pagination for gh api reads of paginated GitHub list endpoints (PR reviews/comments/files, issue comments, pulls, issues) — --paginate --slurp piped to external jq, single-page bounds, newest-first walks. Use before composing any gh api list-endpoint call or any cross-page jq operation (sort_by | last, reverse).
----
-
-# gh API Pagination Rule
-
-**Root cause:** GitHub REST API list endpoints paginate by default. Without `--paginate --slurp`, callers see only the oldest page, and cross-page jq operations (e.g., `sort_by | last`) operate within a single page — producing wrong-but-confident results.
-
-**Rule:** All `gh api` calls that read `pulls/<number>/reviews`, `pulls/<number>/comments`, `issues/<number>/comments`, or any other paginated GitHub list endpoint **must** request the full set of pages AND apply any cross-page jq operation through external `jq`, not through `gh`'s built-in `--jq`. Use `--paginate --slurp | jq` (preferred — see [Safe patterns](#safe-patterns)). Never call these endpoints with their default pagination, and never use `gh`'s `--jq` for cross-page operations like `sort_by | last` or `| reverse | .[0]`.
-
-## Two defects, one rule
-
-This rule guards against two distinct silent-truncation defects that compound:
-
-1. **Default page truncation.** Without `--paginate`, only the first page is fetched.
-2. **`--jq` runs per-page, not on the concatenated result.** Per [GitHub CLI #10459](https://github.com/cli/cli/issues/10459), `gh api --paginate --jq '<filter>'` applies `<filter>` to each page **separately** and emits one output per page. Cross-page operations like `sort_by(.submitted_at) | last` therefore operate within each page independently, not across the merged result set.
-
-The safe patterns below fix both defects together: `--paginate --slurp` walks every page AND emits a single merged structure, and an **external** `jq` then runs cross-page operations on that merged structure.
-
-## Affected endpoints
-
-The rule applies to every paginated read from the GitHub REST API. Common offenders in PR-loop skills:
-
-- `gh api repos/<owner>/<repo>/pulls/<number>/reviews`
-- `gh api repos/<owner>/<repo>/pulls/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls/<number>/files`
-- `gh api repos/<owner>/<repo>/issues/<number>/comments`
-- `gh api repos/<owner>/<repo>/pulls`
-- `gh api repos/<owner>/<repo>/issues`
-
-The same rule applies to any other endpoint documented as paginated by GitHub (see [GitHub REST API pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)).
-
-Single-object endpoints (e.g., `repos/<owner>/<repo>/pulls/<number>` returning one PR object) are not paginated — `?per_page=...` is silently ignored, and neither `--paginate` nor external `jq` is required. Use `gh`'s `--jq` directly on those endpoints.
-
-## Safe patterns
-
-### Preferred — `--paginate --slurp` piped to external `jq`
-
-`gh api ... --paginate --slurp` walks every page and emits a single merged JSON array of page-arrays (`[[page1_items...], [page2_items...], ...]`). Pipe to external `jq` to flatten and filter across the full result set:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | last'
-```
-
-The `.[][]` flattens the array-of-pages into one stream of items before the cross-page operators (`sort_by`, `last`, `reverse`) run. Combine with `?per_page=100` to reduce round-trips on long PRs.
-
-`gh`'s `--jq` flag and `--slurp` flag are mutually exclusive (gh CLI rejects `--paginate --slurp --jq` with `the --slurp option is not supported with --jq or --template`), which is why the filter must run in an external `jq` invocation.
-
-### Acceptable — single-page bound on a paginated list endpoint when result fits
-
-When you have an explicit reason to read at most one page from a **paginated** list endpoint (e.g., a known-small list), document the bound in a comment and use `?per_page=100` without `--paginate`. Cross-page operators are not in play here, so `gh`'s `--jq` is safe:
-
-```bash
-# Bound: a freshly created issue is expected to have <= 100 comments.
-gh api 'repos/<owner>/<repo>/issues/<number>/comments?per_page=100' \
-  --jq '[.[] | select(.user.login=="cursor[bot]")] | length'
-```
-
-This pattern is only safe when the endpoint is confirmed to return a list smaller than 100 entries. Lists that grow over the PR's lifetime (reviews, comments) must use `--paginate --slurp` plus external `jq`.
-
-### Single-object endpoints — no pagination needed
-
-Endpoints that return a single object (e.g., `pulls/<number>`, `issues/<number>`) are not paginated. `?per_page=...`, `--paginate`, and `--slurp` are all unnecessary. Use `gh`'s built-in `--jq` directly:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>' --jq '.head.sha'
-```
-
-### Newest-first walk
-
-Pair pagination with explicit reverse-sort so the consumer reads newest-first regardless of the API's internal order:
-
-```bash
-gh api 'repos/<owner>/<repo>/pulls/<number>/reviews?per_page=100' --paginate --slurp \
-  | jq '[.[][] | select(.user.login=="cursor[bot]")] | sort_by(.submitted_at) | reverse'
-```
-
-This is the canonical pattern for the bugbot <-> bugteam convergence loop: walk newest-first, stop at the first clean review.
-
-## Enforcement
-
-This rule is documentation-only at present. A future PreToolUse hook may pattern-match `Bash` invocations of `gh api repos/.../pulls/<n>/(reviews|comments)` without `--paginate --slurp` (or with `--paginate --jq` doing cross-page operations) and return a corrective message. Until that hook lands, treat this rule as binding by review and rely on it during skill authoring.

package/skills/gotcha/CLAUDE.md

@@ -1,33 +0,0 @@
-# gotcha skill
-
-Captures an obstacle encountered during a skill run and records it as a gotcha entry in the relevant skill file, then opens a draft PR via the `fresh-branch` skill.
-
-**Trigger:** `/gotcha`, "add a gotcha", "document this gotcha", "record this obstacle".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full workflow: collect obstacle details, delegate to `bg-agent`, confirm to user |
-
-## Workflow
-
-1. Distill the obstacle into: which skill file was affected, what happened, what the user did to resolve it, and what to do differently next time.
-2. Invoke `/bg-agent` with a self-contained prompt that instructs the agent to use `/fresh-branch` (branch name `gotcha/<short-slug>`), append to or create a `## Gotchas` section at the bottom of the skill file, commit, push, and open a draft PR.
-3. Confirm to the user that the recording is running in the background.
-
-## Gotcha entry format
-
-Each entry is a bullet under `## Gotchas`:
-
-```markdown
-- **<title>:** <what happens>. <what to do instead>.
-```
-
-## Repo routing
-
-| Skill location | Target repo |
-|---|---|
-| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-dev-env` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` |
-| Project `.claude/skills/<name>/` | That project's repo |

package/skills/gotcha/SKILL.md

@@ -1,73 +0,0 @@
----
-name: gotcha
-description: When a skill encounters an obstacle requiring user intervention, this skill invokes bg-agent to add the gotcha to the skill file's gotcha section and creates a PR via fresh-branch. Triggers on "/gotcha", "add a gotcha", "document this gotcha", "record this obstacle".
----
-
-# gotcha
-
-## Overview
-
-When a skill is executed and hits an obstacle that requires user intervention to resolve, `/gotcha` captures that knowledge so future invocations avoid the same trap. It delegates the mechanical work to `bg-agent`, which writes the gotcha entry and opens a PR using `fresh-branch`.
-
-**Announce at start:** "Recording this gotcha and opening a PR."
-
-## Instructions
-
-### Step 1 — Collect the gotcha
-
-The caller provides the obstacle context. Distill it into:
-
-- **Which skill file** hit the obstacle (full path, e.g. `packages/claude-dev-env/skills/rebase/SKILL.md`).
-- **What happened** — the specific failure or blocker, in one or two sentences.
-- **What the user had to do** to resolve it.
-- **What to do differently next time** (the actionable gotcha).
-
-Determine which repo the skill lives in. Usually this is `claude-dev-env`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
-
-### Step 2 — Delegate to bg-agent
-
-Invoke `/bg-agent` with a task like:
-
-```
-bg-agent add a gotcha to <skill-file-path> in repo <repo-name>. The gotcha is: "<one-line summary>". Details: "<what happened, what the user did, and what to do next time>."
-
-Steps:
-1. Use /fresh-branch to create a branch named gotcha/<short-slug>.
-2. In <skill-file-path>, add the gotcha entry under a ## Gotchas section (create the section at the bottom of the file if it does not exist).
-3. Format each gotcha as a bullet: "- **<title>:** <description>."
-4. Commit with message "fix(<skill-name>): add gotcha — <title>".
-5. Push and create a draft PR.
-6. Report the PR URL.
-```
-
-The bg-agent will pick a suitable agent type and run the full workflow in the background.
-
-### Step 3 — Confirm
-
-Tell the user: "Recording gotcha in the background. You will be notified when the PR is ready."
-
-## Gotcha entry format
-
-Every gotcha entry follows this format:
-
-```markdown
-## Gotchas
-
-- **<title>:** <what happens>. <what to do instead>.
-```
-
-If a `## Gotchas` section already exists, append to it. If not, create it at the bottom of the skill file.
-
-## Which repo
-
-| Skill location | Repo |
-|---|---|
-| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-dev-env` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` (user skills) |
-| Project `.claude/skills/<name>/` | That project's repo |
-
-When unsure, ask the user which repo. Otherwise, default to `claude-dev-env`.
-
-## Gotchas
-
-- **The bg-agent prompt must be self-contained.** The background agent has no access to this conversation. Include the skill file path, the gotcha text, the repo, and the exact workflow steps in the prompt.