@clipboard-health/ai-rules 2.15.4 → 2.15.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.15.4",
+  "version": "2.15.6",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/skills/babysit-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: babysit-pr
-description: "Watch a PR through CI and review feedback: commit/push, wait for CI, auto-fix high-confidence failures, reply to active review threads, and summarize parsed CodeRabbit review-body comments with sentinel-tagged comments. Runs once by default; pass a short interval like `30s` or `2m` for best-effort same-turn polling; longer cadences should use an external loop wrapper. Use when the user says 'babysit my PR', 'watch my PR', 'keep my PR moving', 'respond to comments', or 'loop on CI'."
-argument-hint: "[interval]"
+description: "Watch a PR through CI and review feedback: commit/push, wait for CI, auto-fix high-confidence failures, reply to active review threads, and summarize parsed CodeRabbit review-body comments with sentinel-tagged comments. Runs one pass against the current branch's PR; pass a PR number or URL to `gh pr checkout` that PR first. Use when the user says 'babysit my PR', 'babysit PR 482', 'watch my PR', 'keep my PR moving', or 'respond to comments'."
+argument-hint: "[pr-number-or-url]"
 ---
 
 # Babysit PR
@@ -12,22 +12,16 @@ This skill is self-contained: it does not invoke other skills. It works in Claud
 
 ## Inputs
 
-Parse an optional interval from the invocation arguments if the host exposes them; otherwise read the user's request text.
+Parse an optional PR number or URL from the invocation arguments if the host exposes them; otherwise read the user's request text. Parse in **this priority order** and stop at the first match — do not fall back to a generic "first integer in prose" regex, which would grab unrelated numbers (issue refs, quoted counts, etc.):
 
-Recognize intervals with this regex (case-insensitive):
+1. **Full PR URL** — if `$ARGUMENTS` or the user's text contains `https?://github\.com/[^/\s]+/[^/\s]+/pull/\d+`, capture the URL and pass it to `gh pr checkout` as-is.
+2. **Explicit PR token** — match `(?:PR|pr|pull request)\s*#?(\d+)` or a bare `#(\d+)` in the user's text. Capture the numeric group.
+3. **Bare numeric argument** — only when the entire `$ARGUMENTS` string is a positive integer (no surrounding prose).
+4. **None of the above** — operate on the PR for the current branch (existing Step 2 behavior).
 
-```regex
-\b(\d+)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours)\b
-```
-
-Rules:
+When a match is found, the checkout happens in Preflight before Step 2.
 
-- If multiple matches appear in the user's text, take the **first** match.
-- Accept a bare number as seconds **only** when the bare number is the entire argument (not embedded in prose).
-- Normalize to seconds: `s*=1`, `m*=60`, `h*=3600`.
-- Empty → one iteration, then exit with a summary.
-- Normalized `<= 240` → best-effort same-turn loop: `sleep <seconds>` between iterations.
-- Normalized `> 240` → run one pass, then report that longer cadences need an external loop wrapper (the Claude Code `/loop` skill or a shell `while` loop outside the agent). Do not sleep inside the agent turn — blocking `sleep` past ~5 minutes will exceed prompt-cache TTLs and may hit tool-call timeouts.
+This skill always runs exactly one pass. It never waits or repeats internally. For recurring execution, wrap the call with `/loop <cadence> /babysit-pr` or an external shell `while` loop.
 
 ## Sentinels
 
@@ -72,12 +66,22 @@ gh auth status
 
 If this fails, stop and tell the user to run `gh auth login`.
 
+If a PR number or URL was parsed from Inputs, check out that PR now:
+
+```bash
+gh pr checkout <pr-number-or-url>
+```
+
+This switches the local worktree to the PR's head branch (and handles forks automatically). If the command fails (PR not found, conflicting local branch, etc.), stop and report. The `git status --short` check above runs first so we never check out over dirty work.
+
 ### 2. Locate the PR
 
 ```bash
 gh pr view --json number,url,headRefName,statusCheckRollup 2>/dev/null
 ```
 
+If Preflight checked out a PR explicitly, `gh pr view` will find it by construction and the fallback below does not apply. The fallback only fires when no PR number was supplied and the current branch has no open PR.
+
 If no PR exists for the current branch:
 
 - Verify there are commits ahead of the base branch: `git log --oneline @{u}..HEAD 2>/dev/null || git log --oneline origin/HEAD..HEAD`. If nothing is ahead, stop and report "no commits to push".
@@ -278,7 +282,7 @@ Report:
 - Review threads replied to, grouped by verdict (including any Defer count: "X threads deferred as follow-ups").
 - Nitpicks summarized (or skipped because already covered), including the Deferred count: "Y nitpicks deferred as follow-ups".
 - Threads left active because of bot-acknowledgement uncertainty (flag by thread URL).
-- The stop condition triggered for this iteration (clean / stuck / continue / long-interval / sanity-cap).
+- The stop condition triggered for this pass (clean / progressing / stuck).
 
 When the report mentions any deferrals, include a one-liner the user can run later to enumerate them, e.g.:
 
@@ -290,20 +294,18 @@ Do not rely only on `gh pr view --json comments,reviews` — that view can miss
 
 ## Loop control
 
-After an iteration, pick exactly one outcome:
-
-- **Exit clean** — all CI checks passed AND every thread in `activeThreads` was either marked Skip-reply during step 6's inspection or has already received a fresh sentinel reply in this iteration (Agree / Disagree / Already-fixed / **Defer** all count — a Defer reply is a sentinel reply), AND every current nitpick fingerprint is covered by an existing sentinel comment (deferred nitpicks count; they're in the summary's fingerprint block). Do not use raw `totalActiveThreads` from the script output — it is pre-inspection and will stay non-zero for Skip-reply cases. A PR with Deferred threads is still clean from babysit's perspective: the skill has done what it can without widening scope. Report success and stop.
-- **Exit stuck** — iteration made no commits, posted no new replies, and no CI check changed state from the previous iteration. Report state and stop; tell the user to investigate.
-- **Continue** — interval set, normalized `<= 240`, not clean, not stuck:
+After the single pass completes, pick exactly one outcome:
 
-  ```bash
-  sleep <interval-seconds>
-  ```
+- **Exit clean** — all CI checks passed AND every thread in `activeThreads` was either marked Skip-reply during step 6's inspection or has already received a fresh sentinel reply in this pass (Agree / Disagree / Already-fixed / **Defer** all count — a Defer reply is a sentinel reply), AND every current nitpick fingerprint is covered by an existing sentinel comment (deferred nitpicks count; they're in the summary's fingerprint block). Do not use raw `totalActiveThreads` from the script output — it is pre-inspection and will stay non-zero for Skip-reply cases. A PR with Deferred threads is still clean from babysit's perspective: the skill has done what it can without widening scope. Report success and stop.
+- **Exit progressing** — pass made commits, posted new replies, or both, and the PR is not yet clean (CI is still pending, a new CI run was triggered by this pass's commits, or more work remains). There is real work still in flight that another run would pick up. Report what was done and what is pending, and tell the user to re-run `/babysit-pr` once CI settles, or to wrap the call with `/loop <cadence> /babysit-pr` (or a shell `while true; do ...; done`) for automatic re-runs.
+- **Exit stuck** — pass made no commits and posted no new replies, and the PR is still not clean. Nothing actionable happened this pass. Use this whenever progress is blocked on something outside the skill's scope, including:
+  - CI still running (`gh pr checks --watch` timed out with pending checks).
+  - CI failing with a diagnosis-only verdict from Step 5 (flaky / infra / auth / external check / ambiguous / out-of-scope failure).
+  - Only Skip-reply threads remained AND CI was already red or pending.
 
-  Then go back to step 1.
+  Report the specific blocker (pending vs. diagnosed-failure, with the diagnosis text) and tell the user to investigate or re-run once state may have changed.
 
-- **Long interval** — interval set, normalized `> 240`. Do not sleep. Run one pass, report state, and tell the user to wrap the call in an external loop (Claude Code `/loop <interval> /babysit-pr` or a shell `while true; do ...; sleep ...; done`).
-- **Sanity cap** — hard-stop at 20 iterations regardless, with a clear "sanity cap hit" message. The cap only applies to internal looping.
+This skill never waits or repeats internally.
 
 ## Portability notes
 
@@ -319,20 +321,22 @@ After an iteration, pick exactly one outcome:
 
 User: `babysit my PR`
 
-- No interval → one iteration.
+- No PR arg → operate on the current branch.
 - Preflight OK, PR #482 found.
 - `gh pr checks --watch` times out at 600s — two checks still pending.
 - `unresolvedPrComments.sh` returns 0 active threads, 0 nitpicks.
 - No commits, no replies posted, CI state unchanged vs. start.
-- Outcome: **stuck**. Report: "CI still running after 10 min; no comments to address. Re-run `/babysit-pr 2m` once CI settles, or wait and invoke again."
+- Outcome: **stuck**. Report: "CI still running after 10 min; no comments to address. Re-run `/babysit-pr` once CI settles, or wrap with `/loop 2m /babysit-pr`."
 
-### Example 2: `babysit-pr 2m` loop, exits clean on iteration 3
+### Example 2: explicit PR number checks out and babysits that PR
 
-User: `babysit-pr 2m`
+User: `babysit PR 482`
 
-- Iteration 1: CI green, 3 active threads (1 Agree, 1 Disagree, 1 Already-fixed), 2 nitpicks (both Agree). Apply fixes, commit `a1b2c3d`, post 3 thread replies + 1 nitpick summary. Not clean (CI needs to re-run), not stuck. `sleep 120`.
-- Iteration 2: CI fails (lint on the nitpick fix). Log shows unused import. High-confidence + in scope → remove import, commit `d4e5f6a`, push. Threads are all addressed. `sleep 120`.
-- Iteration 3: CI green, 0 active threads, 0 new nitpick fingerprints. **Exit clean.** Report final commit SHAs and reply URLs.
+- Preflight OK. Input parser matches the explicit-token rule and captures `482`.
+- `gh pr checkout 482` switches the worktree to PR #482's head branch (say, `feat/xyz`).
+- Step 2's `gh pr view` confirms PR #482 on the now-current branch; the new-PR fallback does not fire.
+- Remainder proceeds as a normal single pass (CI watch, thread / nitpick assessment, replies).
+- Report final state on exit.
 
 ### Example 3: out-of-scope nitpick gets deferred
 
@@ -353,4 +357,4 @@ User: `babysit my PR`
 
 ## Input
 
-Interval: $ARGUMENTS
+PR number or URL: $ARGUMENTS

package/skills/fix-ci/SKILL.md

@@ -1,85 +0,0 @@
----
-name: fix-ci
-description: "Analyze and fix CI failures for a GitHub pull request. Use this when CI checks are failing, the build is red, or you need to diagnose GitHub Actions failures. Triggers on: 'fix CI', 'CI is failing', 'checks failed', 'build is broken', 'tests failing in CI', 'why is CI red', or any request to investigate and resolve PR check failures."
-argument-hint: "[pr-url]"
----
-
-# Fix CI Failures
-
-Diagnose and fix CI failures for a GitHub pull request by retrieving logs, identifying root causes, and applying targeted fixes.
-
-## Arguments
-
-- `$ARGUMENTS` - GitHub PR URL (e.g., `https://github.com/owner/repo/pull/123`). If omitted, uses the PR for the current branch.
-
-## Instructions
-
-### Step 1: Get PR and Identify Failed Checks
-
-```bash
-# If $ARGUMENTS contains a PR URL, extract the PR number from the path.
-# Otherwise, get the PR for the current branch:
-gh pr view --json number,url,headRefName,statusCheckRollup
-```
-
-From `statusCheckRollup`, find checks where `conclusion` is `"failure"` or `state` is `"FAILURE"`. If no checks have failed, report that CI is green and stop.
-
-When multiple checks failed, prioritize **build/compile checks over test checks** — build errors are often the root cause of downstream test failures, so fixing them first may resolve multiple failures at once.
-
-### Step 2: Retrieve Failed Job Logs
-
-Extract the run ID from the failed check's `detailsUrl` (the numeric suffix of the GitHub Actions URL, e.g., `.../actions/runs/123456789`).
-
-```bash
-# List failed job IDs for the run
-gh run view $RUN_ID --json jobs --jq '.jobs[] | select(.conclusion == "failure") | .databaseId'
-
-# Get only failed step output (concise)
-gh run view --job $JOB_ID --log-failed
-```
-
-Start with `--log-failed` because it shows only the output from failed steps, cutting through potentially thousands of lines of passing output. Only fall back to `--log` with targeted grep if `--log-failed` doesn't provide enough context.
-
-When parsing large log output, focus on:
-
-- **The first error message** — later failures often cascade from this
-- **Summary lines** like "Test Suites:", "FAILED", build error counts
-- **Stack traces** immediately after assertion or compilation errors
-
-### Step 3: Diagnose Root Cause
-
-Read the relevant source files and tests to understand the failure in context.
-
-**Build/compilation errors** — type errors, missing imports, syntax issues. These block everything else.
-**Test failures** — read both the failing test and the code it exercises. The fix could be in either place; don't assume the test is wrong just because it's failing.
-**Lint/format errors** — usually auto-fixable with project formatting tools.
-**Infrastructure issues** — missing env vars, CI config problems, dependency resolution failures.
-
-### Step 4: Present Findings and Proposed Fix
-
-Before changing code, present:
-
-1. **Root cause** — what's failing and why
-2. **Proposed fix** — which files to change and what the changes are
-
-Then ask the user whether to proceed. This confirmation step matters because CI failures can be ambiguous — what looks like a test bug might actually be the test correctly catching a real regression.
-
-### Step 5: Apply Fix and Verify
-
-After approval, implement the changes. Then run the relevant checks locally (build, test, lint for the affected project/files) to verify the fix before pushing. Report the local results.
-
-### Failure Patterns
-
-**Removed code but tests still reference it:** Delete or update the tests. Check for leftover references in shared test fixtures or configurations.
-
-**Missing mocks/providers after adding a dependency:** Add the mock to test module setup. Update existing mocks when signatures change.
-
-**Type errors from interface changes:** Fix in the changed files. If the type change is intentional, update downstream consumers too.
-
-**Snapshot mismatches:** Check if the change is expected (you modified rendering/output). If so, update snapshots. If not, investigate the regression.
-
-**Flaky/intermittent failures:** If the test passes locally, the failure looks timing-dependent, or it's unrelated to the PR's changes, flag this to the user rather than making speculative changes.
-
-## Input
-
-Pull Request URL: $ARGUMENTS

package/skills/iterate-pr/SKILL.md

@@ -1,135 +0,0 @@
----
-name: iterate-pr
-description: "Iteratively commit, push, and address PR feedback until CI passes and comments are resolved. Use this skill when the user wants to get a PR to a mergeable state, fix CI and address review comments in a loop, or says things like 'iterate on my PR', 'make this PR pass', 'fix everything on the PR', 'get this PR ready to merge', or 'keep going until CI is green'."
-argument-hint: "[max-iterations]"
----
-
-# Iterate PR
-
-Autonomously iterate on a pull request until CI checks pass and all comments are resolved. Each iteration runs in a fresh subagent.
-
-## Arguments
-
-- `$ARGUMENTS` - Maximum iterations (default: 3)
-
-## Instructions
-
-### Step 1: Initialize
-
-Parse max iterations from `$ARGUMENTS` (default: 3). Set iteration counter to 0.
-
-### Step 2: Check State
-
-Get the PR for the current branch:
-
-!`gh pr view --json number,url,headRefName,statusCheckRollup 2>/dev/null || echo "NO_PR"`
-
-**If no PR exists:** Proceed to Step 3 (first iteration will create one).
-
-**If PR exists:** Get unresolved comments data:
-
-!`bash "${CLAUDE_PLUGIN_ROOT:-.agents}/skills/unresolved-pr-comments/scripts/unresolvedPrComments.sh" 2>/dev/null`
-
-Parse the JSON output and evaluate exit conditions.
-
-**If any CI checks are still PENDING, QUEUED, or IN_PROGRESS:** Proceed to Step 3 regardless of comment count. Automated reviewers (e.g. CodeRabbit) may not have posted comments yet, so comment data is unreliable until all checks complete.
-
-**If statusCheckRollup is empty or null:** Treat CI as passing (some PRs have no required checks configured).
-
-**Exit with success** when ALL conditions are met:
-
-- All CI checks have completed (no PENDING, QUEUED, or IN_PROGRESS statuses in statusCheckRollup) and none have failed (or no checks exist)
-- No unresolved comments (totalUnresolvedComments == 0)
-- No nitpicks (totalNitpicks == 0)
-
-**JSON Structure for Exit Evaluation:**
-
-```json
-{
-  "totalUnresolvedComments": number,
-  "totalNitpicks": number,
-  "unresolvedComments": [...],
-  "nitpickComments": [...]
-}
-```
-
-Check `totalUnresolvedComments == 0` and `totalNitpicks == 0` for exit condition.
-
-Report: "PR is clean! All CI checks pass and no unresolved comments."
-
-**Exit with status report** when iteration counter >= max iterations:
-
-- List failing CI checks
-- List unresolved comment/nitpick counts
-- Suggest running `/iterate-pr` again to continue
-
-### Step 3: Spawn Iteration Subagent
-
-Spawn a Task subagent with `subagent_type: "general-purpose"` using this prompt:
-
-> Handle one iteration of the PR feedback loop:
->
-> 1. **Record Starting Commit**: !`git rev-parse HEAD` (save as `startCommit`)
-> 2. **Commit and Push**: Invoke `core:commit-push-pr` via the Skill tool
-> 3. **Get PR Number**: !`gh pr view --json number --jq '.number'`
-> 4. **Wait for CI**: !`rc=0; if command -v gtimeout >/dev/null 2>&1; then gtimeout 600 gh pr checks --watch || rc=$?; elif command -v timeout >/dev/null 2>&1; then timeout 600 gh pr checks --watch || rc=$?; else gh pr checks --watch || rc=$?; fi; case $rc in 0|1|8|124) ;; *) exit $rc;; esac` (10 minute timeout; exit codes: 0=pass, 1=fail, 8=pending, 124=timeout are expected and handled in next step; other codes like 4=auth error are re-raised; uses gtimeout on macOS, timeout on Linux, no timeout as fallback)
-> 5. **Check CI Status**: Run `gh pr checks --json name,state,bucket` and parse the output
->    - If any check has `bucket: "fail"`, invoke `core:fix-ci` via the Skill tool. Since you are running autonomously, do NOT wait for user approval — apply the fixes directly. Report what was fixed and exit.
-> 6. **Check Comments**: Run `bash "${CLAUDE_PLUGIN_ROOT:-.agents}/skills/unresolved-pr-comments/scripts/unresolvedPrComments.sh"` and parse the JSON output
->    - If unresolved comments or nitpicks exist:
->      1. Group comments by file path and read each file once (not per-comment)
->      2. If a file no longer exists, note the comment may be outdated and skip it
->      3. Assess each comment with an explicit verdict:
->         - **Agree**: Explain why, then fix it
->         - **Disagree**: Explain why the current code is acceptable; do NOT change the code
->         - **Already fixed**: Note that the code already addresses this concern
->      4. After assessing all comments, fix only those you agreed with and exit (next iteration will commit fixes)
-> 7. **Report**: Run `git rev-parse HEAD` and compare to `startCommit` to determine if commits were made. Include PR status, CI status, and comments addressed
-
-### Step 4: Loop
-
-After the subagent completes:
-
-1. Increment iteration counter
-2. If no commits were made this iteration:
-   - Get unresolved comments by running: `bash "${CLAUDE_PLUGIN_ROOT:-.agents}/skills/unresolved-pr-comments/scripts/unresolvedPrComments.sh"`
-   - If unresolved comments remain, exit with: "Comments addressed, awaiting reviewer resolution. Run `/iterate-pr` after reviewer responds."
-3. Report: "Iteration [N]/[max] complete. Checking state..."
-4. Return to Step 2
-
-## Examples
-
-**Successful completion:**
-
-```text
-Iteration 1/3: No PR exists
-> commit-push-pr -> PR #347 created
-> CI failed (lint errors) -> fix-ci -> fixed missing semicolons
-
-Iteration 2/3: CI failures remain
-> commit-push-pr -> pushed fixes
-> CI passed, 2 review comments
-> unresolved-pr-comments -> addressed null check, const usage
-
-Iteration 3/3: Comments pending
-> commit-push-pr -> pushed fixes
-> CI passed, no unresolved comments
-
-PR is clean! All CI checks pass and no unresolved comments.
-```
-
-**Awaiting reviewer resolution:**
-
-```text
-Iteration 1/3: PR exists with comments
-> commit-push-pr -> pushed comment fixes
-> CI passed, 1 comment remains (disagreed with suggestion)
-
-Iteration 2/3: No commits made, comments remain
-
-Comments addressed, awaiting reviewer resolution. Run `/iterate-pr` after reviewer responds.
-```
-
-## Input
-
-Maximum iterations: $ARGUMENTS

package/skills/learn-from-session/SKILL.md

@@ -1,123 +0,0 @@
----
-name: learn-from-session
-description: |
-  Analyze the current session for agent efficiency, quality, and actionable improvements. Use this skill when the user says things like "learn from this session", "session retro", "what went well", "how did the agent do", "what should I improve", "review this session", "session review", or any request to reflect on how the current session went. Also use when the user wants to extract learnings, identify friction, or improve their workflow based on what just happened.
----
-
-You are reviewing the current Claude Code session. Your job is to surface the 2-3 most impactful findings — things that would actually change how the next session goes — not to produce an exhaustive report card.
-
-Be candid. A session where everything scores 4/5 but you have nothing concrete to suggest is a wasted review. Prioritize specificity over coverage: one sharp observation beats five generic ones.
-
-Analyze the session transcript and produce the following:
-
-## Agent efficiency analysis
-
-Evaluate how well the agent used tools and how much human course-correction was needed.
-
-Score each dimension 1-5. Calibration: 1=actively harmful or completely wrong approach, 2=significant waste or frequent missteps, 3=adequate but with clear room for improvement, 4=good with minor issues, 5=genuinely impressive and hard to improve on. Reserve 5 for sessions that would make you say "I wish the agent always worked like this."
-
-- **Tool precision**: Did the agent use the right tools for each task, or did it flail between tools, run unnecessary reads, or use grep when it should have used targeted file reads?
-- **Iteration efficiency**: How many attempts did it take to get things right? Count tool retries, failed bash commands, and edit-then-re-edit cycles.
-- **Context utilization**: Did the agent leverage CLAUDE.md, AGENTS.md, and project conventions, or did it ignore available context and make assumptions?
-- **Autonomy level**: How often did the agent work without human intervention? Each rejection/abort/course-correction is a friction event.
-- **Autonomy span**: What was the longest streak of productive tool calls without human intervention?
-
-Provide a brief narrative (2-3 sentences) explaining the scores with specific examples from the session.
-
-## Agent quality analysis
-
-Evaluate how well the agent followed project coding standards and CLAUDE.md rules.
-
-Use the same 1-5 calibration as above.
-
-- **CLAUDE.md compliance**: Did the agent follow the rules and conventions defined in CLAUDE.md and AGENTS.md? Flag specific violations.
-- **Code pattern adherence**: Did the generated code follow established project patterns (naming conventions, error handling, file organization, test structure)?
-- **Test coverage intent**: Did the agent write or update tests when modifying behavior? Did it run tests before declaring done?
-- **PR hygiene**: Is the commit history clean? Are changes scoped appropriately? Did the agent avoid touching unrelated files?
-- **Documentation awareness**: Did the agent update relevant docs, comments, or type definitions when changing interfaces?
-
-Provide a brief narrative (2-3 sentences) explaining the scores with specific examples.
-
-## Session reflection
-
-Surface things that would save time if known at the start of the next session. The bar for inclusion: "would I tell a teammate about this before they start working on this codebase?" Skip categories with nothing worth noting.
-
-- **Bash commands**: Commands that were used, discovered, or would have been useful to know upfront.
-- **Code style patterns**: Patterns followed or discovered that aren't yet documented.
-- **Testing approaches**: Testing strategies that worked or should have been used.
-- **Environment/configuration quirks**: Gotchas, workarounds, or setup details encountered.
-- **Warnings**: Errors, deprecations, or edge cases that tripped up the agent.
-
-## Actionable improvements
-
-This is the most important section. Produce recommendations in these categories, but only if genuinely actionable — a suggestion the user can apply in under 5 minutes. Skip any category with nothing worth doing.
-
-### CLAUDE.md updates
-
-**Do not suggest rules that duplicate existing automated enforcement.** If a lint rule, pre-commit hook, CI check, or other tooling already catches an issue, documenting it in CLAUDE.md/AGENTS.md is redundant. Before suggesting a rule, check whether the session transcript shows the error was already caught and blocked by automated tooling (e.g. a pre-commit hook rejected the commit, a linter flagged the issue). If so, skip it — the tooling is already doing its job.
-
-For each suggestion, specify whether it belongs in:
-
-- **Team-shared** (checked into git, e.g. `./CLAUDE.md` or `./AGENTS.md`)
-- **Personal/local** (git-ignored, e.g. `~/.claude/CLAUDE.md`)
-
-Format each as a ready-to-paste diff:
-
-```diff
-+ [the addition - keep it brief]
-```
-
-### Hooks, skills, or agents
-
-Suggest new or revised hooks, skills, or agents that would have prevented issues or improved the workflow.
-
-### Prompt technique
-
-One concrete thing the engineer could do differently in their prompts to get better results (be specific, not generic).
-
-### Agent pattern note
-
-One observation about how the agent behaved that the team should know about — a strength to replicate or a weakness to work around.
-
-## Structured data block
-
-After the human-readable review, emit a fenced JSON block that a scraper can parse:
-
-```json
-{
-  "session_review": {
-    "version": "1.1",
-    "timestamp": "<ISO 8601>",
-    "efficiency": {
-      "tool_precision": <1-5>,
-      "iteration_efficiency": <1-5>,
-      "context_utilization": <1-5>,
-      "autonomy_level": <1-5>,
-      "autonomy_span": <1-5>,
-      "friction_events": <count of rejections/aborts/course-corrections>,
-      "total_tool_calls": <count>,
-      "failed_tool_calls": <count>
-    },
-    "quality": {
-      "claude_md_compliance": <1-5>,
-      "code_pattern_adherence": <1-5>,
-      "test_coverage_intent": <1-5>,
-      "pr_hygiene": <1-5>,
-      "documentation_awareness": <1-5>,
-      "violations": ["<brief description of each CLAUDE.md violation>"]
-    },
-    "improvements": {
-      "claude_md_rules": ["<each suggested rule, ready to paste>"],
-      "hooks_skills_agents": ["<each suggestion>"],
-      "prompt_technique": "<the suggestion>",
-      "agent_pattern_note": "<the observation>"
-    }
-  }
-}
-```
-
-## Presenting the review
-
-1. Display the human-readable sections.
-2. If there is an open PR for the current branch, offer to post the review as a PR comment (using `gh pr comment` with `--body-file`).
-3. If the user has CLAUDE.md updates to apply, offer to apply them directly.

package/skills/unresolved-pr-comments/SKILL.md

@@ -1,47 +0,0 @@
----
-name: unresolved-pr-comments
-description: "Get unresolved review comments from a GitHub pull request. Use this skill when the user asks about PR feedback, review comments, unresolved threads, what reviewers said, CodeRabbit review-body comments, or wants to address PR review feedback. Also use when the user says 'check my PR', 'what's left on my PR', or 'resolve comments'."
-argument-hint: "[pr-number]"
----
-
-# Unresolved PR Comments
-
-Fetch and analyze unresolved review comments from a GitHub pull request.
-
-## Usage
-
-Run the script to fetch PR comment data:
-
-```bash
-bash scripts/unresolvedPrComments.sh [pr-number]
-```
-
-If no PR number is provided, it uses the PR associated with the current branch.
-
-Note: Limited to 100 review threads, 10 comments per thread, and 100 reviews.
-
-## Processing Instructions
-
-Using the JSON output from the script:
-
-1. **If error**: Display the error message and suggest the fix
-2. **If no comments**: Report the PR has no pending feedback
-3. **If comments exist**: Present a brief summary (e.g., "Found 3 unresolved comments and 5 CodeRabbit review-body comments")
-
-Then, for EVERY comment (both `unresolvedComments` AND `nitpickComments`):
-
-1. Group comments by file path and read each file once (not per-comment)
-2. If a file no longer exists, note that the comment may be outdated
-3. Assess each comment against the current code. When multiple comments appear at the same file and line, they are part of the same review thread — read them together as a conversation
-4. Group your assessment as follows:
-
-   **Should address**
-   - Description of the comment with file path(s)
-     - Why it's a real issue (bug, a11y, UX, etc.)
-
-   **Can ignore**
-   - Description of the comment with file path(s)
-     - Why: already fixed, not actionable, not worth addressing in this PR, etc.
-
-   **Net**
-   Summary of how many are worth fixing and what kind of issues they are. Offer to fix, but **do NOT start until the user confirms**.

package/skills/unresolved-pr-comments/scripts/parseNitpicks.sh

@@ -1,165 +0,0 @@
-#!/usr/bin/env bash
-# parseNitpicks.sh — Parse CodeRabbit review-body comments from PR review bodies.
-# Sourced by unresolvedPrComments.sh. Requires: jq, perl.
-
-# Extract CodeRabbit review-body comments from reviews JSON (passed via stdin).
-# Outputs a JSON array of comment objects. The function name is retained for
-# backward compatibility with existing skill scripts.
-extract_nitpick_comments() {
-  local reviews_json="$1"
-
-  printf '%s' "$reviews_json" | perl -e '
-use strict;
-use warnings;
-use JSON::PP;
-
-local $/;
-my $reviews_json = <STDIN>;
-my $reviews = decode_json($reviews_json);
-
-# Find latest coderabbitai review with supported review-body comment sections.
-my $latest_review;
-my $latest_time = "";
-for my $review (@$reviews) {
-  my $author = $review->{author}{login} // "";
-  my $body = $review->{body} // "";
-  next unless $author eq "coderabbitai" && has_supported_sections($body);
-  my $created = $review->{createdAt} // "";
-  if ($created gt $latest_time) {
-    $latest_time = $created;
-    $latest_review = $review;
-  }
-}
-
-unless ($latest_review) {
-  print "[]";
-  exit 0;
-}
-
-my $body = $latest_review->{body};
-my $author = $latest_review->{author}{login} // "deleted-user";
-my $created_at = $latest_review->{createdAt} // "";
-
-my @sections = extract_review_body_comment_sections($body);
-unless (@sections) {
-  print "[]";
-  exit 0;
-}
-
-my @comments;
-for my $section (@sections) {
-  my $section_content = $section->{content};
-  my $category = $section->{category};
-
-  # Extract file sections: <details><summary>filename (count)</summary><blockquote>...</blockquote></details>
-  while ($section_content =~ /<details>\s*<summary>([^<]+?)\s+\(\d+\)<\/summary>\s*<blockquote>([\s\S]*?)<\/blockquote>\s*<\/details>/g) {
-    my $raw_file_name = trim($1);
-    my $file_content = $2;
-
-    # Extract individual comments: `line-range`: severity metadata, **title**, body
-    while ($file_content =~ /`(\d+(?:-\d+)?)`:\s*(?:_[^_]+_\s*\|\s*_[^_]+_\s*)?\*\*([^*]+)\*\*\s*([\s\S]*?)(?=---|\n`\d|<\/blockquote>|$)/g) {
-      my $line_range = $1;
-      my $title = trim($2);
-      my $clean_body = clean_comment_body(trim($3));
-      my $file_name = normalize_file_name($raw_file_name, $line_range);
-      push @comments, {
-        author    => $author,
-        body      => "$title\n\n$clean_body",
-        category  => $category,
-        createdAt => $created_at,
-        file      => $file_name,
-        line      => $line_range,
-      };
-    }
-  }
-}
-
-print encode_json(\@comments);
-
-sub has_supported_sections {
-  my ($text) = @_;
-  $text = strip_markdown_blockquote_prefixes($text);
-  return $text =~ /<summary>\s*[^<]*(?:Nitpick comments|Minor comments|Outside diff range comments)\s*\(\d+\)<\/summary>\s*<blockquote>/i;
-}
-
-sub extract_review_body_comment_sections {
-  my ($text) = @_;
-  $text = strip_markdown_blockquote_prefixes($text);
-
-  my @sections;
-  while ($text =~ /<summary>\s*[^<]*(Nitpick comments|Minor comments|Outside diff range comments)\s*\(\d+\)<\/summary>\s*<blockquote>/ig) {
-    my $category = section_category($1);
-    my $content_start = $+[0];
-    my $after = substr($text, $content_start);
-
-    my $depth = 1;
-    my @tags;
-    while ($after =~ /(<blockquote>|<\/blockquote>)/gi) {
-      my $tag = $1;
-      my $pos = $-[0];
-      my $is_open = ($tag =~ /^<blockquote>/i) ? 1 : 0;
-      push @tags, [$pos, $is_open];
-    }
-    for my $tag (@tags) {
-      $depth += $tag->[1] ? 1 : -1;
-      if ($depth == 0) {
-        push @sections, {
-          category => $category,
-          content  => substr($after, 0, $tag->[0]),
-        };
-        last;
-      }
-    }
-  }
-  return @sections;
-}
-
-sub section_category {
-  my ($label) = @_;
-  return "nitpick" if $label =~ /Nitpick comments/i;
-  return "minor" if $label =~ /Minor comments/i;
-  return "outside-diff" if $label =~ /Outside diff range comments/i;
-  return "unknown";
-}
-
-sub normalize_file_name {
-  my ($file_name, $line_range) = @_;
-  my $suffix = "-" . $line_range;
-  $file_name =~ s/\Q$suffix\E$//;
-  return $file_name;
-}
-
-sub strip_markdown_blockquote_prefixes {
-  my ($text) = @_;
-  $text =~ s/^[ \t]*>[ \t]?//mg;
-  return $text;
-}
-
-sub clean_comment_body {
-  my ($text) = @_;
-  # Iteratively remove innermost <details> elements
-  my $prev = "";
-  while ($text ne $prev) {
-    $prev = $text;
-    $text =~ s/<details>(?:(?!<details>)[\s\S])*?<\/details>//g;
-  }
-  $text =~ s/</&lt;/g;
-  $text =~ s/>/&gt;/g;
-  return trim($text);
-}
-
-sub trim {
-  my ($s) = @_;
-  $s =~ s/^\s+//;
-  $s =~ s/\s+$//;
-  return $s;
-}
-'
-}
-
-# Extract code scanning alert number from comment body.
-# Outputs the alert number or empty string.
-extract_code_scanning_alert_number() {
-  local body="$1"
-  printf '%s' "$body" | perl -ne 'print $1 if m{/code-scanning/(\d+)}'
-}

package/skills/unresolved-pr-comments/scripts/unresolvedPrComments.sh

@@ -1,246 +0,0 @@
-#!/usr/bin/env bash
-# unresolvedPrComments.sh — Fetch unresolved review comments from a GitHub PR.
-# Usage: bash unresolvedPrComments.sh [pr-number]
-# Outputs JSON with unresolved comments and CodeRabbit nitpicks.
-# Compatible with macOS bash 3.2. Requires: gh, jq, perl.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=parseNitpicks.sh
-source "${SCRIPT_DIR}/parseNitpicks.sh"
-
-# Save original stdout so output_error works inside $() command substitutions
-exec 3>&1
-
-# --- Helpers (inlined from ghClient.ts / prClient.ts) ---
-
-output_error() {
-  printf '%s' "$1" | jq -Rsc '{ error: . }' >&3
-  exit 1
-}
-
-validate_prerequisites() {
-  if ! command -v jq >/dev/null 2>&1; then
-    printf '{"error":"jq not found. Install from https://stedolan.github.io/jq"}\n' >&3
-    exit 1
-  fi
-  if ! command -v gh >/dev/null 2>&1; then
-    output_error "gh CLI not found. Install from https://cli.github.com"
-  fi
-  if ! command -v perl >/dev/null 2>&1; then
-    output_error "perl not found."
-  fi
-  if ! gh api user --jq '.login' >/dev/null 2>&1; then
-    output_error "Not authenticated with GitHub. Run: gh auth login"
-  fi
-}
-
-get_pr_number() {
-  local arg="${1:-}"
-  if [ -n "$arg" ]; then
-    if ! printf '%s' "$arg" | grep -qE '^[0-9]+$'; then
-      output_error "Invalid PR number: ${arg}"
-    fi
-    printf '%s' "$arg"
-    return
-  fi
-
-  local pr_json
-  if ! pr_json="$(gh pr view --json number 2>/dev/null)"; then
-    output_error "No PR found for current branch. Provide PR number as argument."
-  fi
-
-  local pr_num
-  pr_num="$(printf '%s' "$pr_json" | jq -r '.number // empty')"
-  if [ -z "$pr_num" ]; then
-    output_error "No PR found for current branch. Provide PR number as argument."
-  fi
-  printf '%s' "$pr_num"
-}
-
-get_repo_info() {
-  local repo_json
-  if ! repo_json="$(gh repo view --json owner,name 2>/dev/null)"; then
-    output_error "Could not determine repository. Are you in a git repo with a GitHub remote?"
-  fi
-
-  REPO_OWNER="$(printf '%s' "$repo_json" | jq -r '.owner.login // empty')"
-  REPO_NAME="$(printf '%s' "$repo_json" | jq -r '.name // empty')"
-
-  if [ -z "$REPO_OWNER" ] || [ -z "$REPO_NAME" ]; then
-    output_error "Failed to parse repository info from gh CLI output."
-  fi
-}
-
-# --- GraphQL ---
-
-# Pagination limits: 100 review threads, 10 comments per thread, 100 reviews.
-# Sufficient for typical PRs; data may be truncated on exceptionally active PRs.
-GRAPHQL_QUERY='
-query($owner: String!, $repo: String!, $pr: Int!) {
-  repository(owner: $owner, name: $repo) {
-    pullRequest(number: $pr) {
-      title
-      url
-      reviewThreads(first: 100) {
-        nodes {
-          isResolved
-          comments(first: 10) {
-            nodes {
-              body
-              path
-              line
-              originalLine
-              author { login }
-              createdAt
-            }
-          }
-        }
-      }
-      reviews(first: 100) {
-        nodes {
-          body
-          author { login }
-          createdAt
-        }
-      }
-    }
-  }
-}'
-
-execute_graphql_query() {
-  local owner="$1" repo="$2" pr_number="$3"
-  local result
-  if ! result="$(gh api graphql \
-    -f "query=${GRAPHQL_QUERY}" \
-    -f "owner=${owner}" \
-    -f "repo=${repo}" \
-    -F "pr=${pr_number}" 2>&1)"; then
-    output_error "GraphQL query failed: ${result}"
-  fi
-  printf '%s' "$result"
-}
-
-# --- Code scanning filter ---
-
-is_code_scanning_alert_fixed() {
-  local owner="$1" repo="$2" alert_number="$3"
-  local result
-  if ! result="$(gh api "repos/${owner}/${repo}/code-scanning/alerts/${alert_number}" 2>/dev/null)"; then
-    return 1
-  fi
-
-  local state
-  state="$(printf '%s' "$result" | jq -r '.most_recent_instance.state // empty')"
-  [ "$state" = "fixed" ]
-}
-
-# --- Main ---
-
-main() {
-  validate_prerequisites
-
-  local pr_number
-  pr_number="$(get_pr_number "${1:-}")"
-
-  get_repo_info
-  local owner="$REPO_OWNER"
-  local repo="$REPO_NAME"
-
-  local response
-  response="$(execute_graphql_query "$owner" "$repo" "$pr_number")"
-
-  # Validate response
-  if [ "$(printf '%s' "$response" | jq -r '.data.repository // empty')" = "" ]; then
-    output_error "Repository ${owner}/${repo} not found or not accessible."
-  fi
-  if [ "$(printf '%s' "$response" | jq -r '.data.repository.pullRequest // empty')" = "" ]; then
-    output_error "PR #${pr_number} not found or not accessible."
-  fi
-
-  local title url
-  title="$(printf '%s' "$response" | jq -r '.data.repository.pullRequest.title')"
-  url="$(printf '%s' "$response" | jq -r '.data.repository.pullRequest.url')"
-
-  # Extract unresolved comments: filter unresolved threads, flatten comments
-  local all_unresolved
-  all_unresolved="$(printf '%s' "$response" | jq '[
-    .data.repository.pullRequest.reviewThreads.nodes[]
-    | select(.isResolved == false)
-    | .comments.nodes[]
-    | {
-        author: (.author.login // "deleted-user"),
-        body: .body,
-        createdAt: .createdAt,
-        file: .path,
-        line: (.line // .originalLine)
-      }
-  ]')"
-
-  # Filter out fixed code-scanning alerts from github-advanced-security
-  local unresolved_comments="[]"
-  local count
-  count="$(printf '%s' "$all_unresolved" | jq 'length')"
-
-  local i=0
-  while [ "$i" -lt "$count" ]; do
-    local comment
-    comment="$(printf '%s' "$all_unresolved" | jq ".[$i]")"
-    local comment_author
-    comment_author="$(printf '%s' "$comment" | jq -r '.author')"
-
-    local keep=true
-    if [ "$comment_author" = "github-advanced-security" ]; then
-      local comment_body alert_number
-      comment_body="$(printf '%s' "$comment" | jq -r '.body')"
-      alert_number="$(extract_code_scanning_alert_number "$comment_body")"
-      if [ -n "$alert_number" ]; then
-        if is_code_scanning_alert_fixed "$owner" "$repo" "$alert_number"; then
-          keep=false
-        fi
-      fi
-    fi
-
-    if [ "$keep" = true ]; then
-      unresolved_comments="$(printf '%s' "$unresolved_comments" | jq --argjson c "$comment" '. + [$c]')"
-    fi
-
-    i=$((i + 1))
-  done
-
-  # Extract nitpick comments from reviews
-  local reviews_json
-  reviews_json="$(printf '%s' "$response" | jq '[.data.repository.pullRequest.reviews.nodes[]]')"
-  local nitpick_comments
-  nitpick_comments="$(extract_nitpick_comments "$reviews_json")"
-
-  # Build final output
-  local total_unresolved total_nitpicks
-  total_unresolved="$(printf '%s' "$unresolved_comments" | jq 'length')"
-  total_nitpicks="$(printf '%s' "$nitpick_comments" | jq 'length')"
-
-  jq -n \
-    --argjson nitpickComments "$nitpick_comments" \
-    --arg owner "$owner" \
-    --argjson prNumber "$pr_number" \
-    --arg repo "$repo" \
-    --arg title "$title" \
-    --argjson totalNitpicks "$total_nitpicks" \
-    --argjson totalUnresolvedComments "$total_unresolved" \
-    --argjson unresolvedComments "$unresolved_comments" \
-    --arg url "$url" \
-    '{
-      nitpickComments: $nitpickComments,
-      owner: $owner,
-      prNumber: $prNumber,
-      repo: $repo,
-      title: $title,
-      totalNitpicks: $totalNitpicks,
-      totalUnresolvedComments: $totalUnresolvedComments,
-      unresolvedComments: $unresolvedComments,
-      url: $url
-    }'
-}
-
-main "$@"