hook-refire-shortcircuit

name	hook-refire-shortcircuit
description	Detailed procedures for hook re-fire short-circuit — sentinel files, CR incremental-mode detection, Branch A caps, stale review dismissal commands
type	reference

Hook Re-fire Short-Circuit — Procedures

This skill contains the operational procedures referenced by the mandatory rules in ~/.claude/CLAUDE.md ("Hook re-fire short-circuit" section). The CLAUDE.md rules are authoritative; this skill provides the implementation detail.

Sentinel caveat

Sentinel files (~/.tmp/HOOK_<name>) only suppress hook fires when the hook template itself checks for them. Most hooks do NOT check ~/.tmp/. Before creating a sentinel, verify the hook script reads from ~/.tmp/. If it doesn't, the sentinel won't work.

No-target-PR procedure

If a UserPromptSubmit hook fires with blank --repo (literal /) and no PR number:

1. Detect it once: if the hook template has gh pr view --repo / with no populated repo field, flag the harness gap.
2. Exit immediately: run gh pr view --json number --jq '.number' (no --repo needed inside a repo worktree) as fallback. If nothing, print "No target PR found — exiting." and stop.
3. Do not loop: if it fires again, check CR review state. If APPROVED → "Branch B — exit silently." Write sentinel only if hook reads ~/.tmp/.
4. Do NOT escalate via /harness: the hook fires on the /harness response itself (self-referential loop). Acknowledge Branch B and stop.

Track count in ~/.tmp/HOOK_no_pr_count.json. Cap at 2.

CR APPROVED PR — stale hook fires

If hook delivers CR CHANGES_REQUESTED on a PR where CR is already APPROVED:

1. Exit silently (Branch B)
2. Write ~/.tmp/HOOK_<pr>_stale sentinel
3. On next re-fire: escalate via /harness immediately

CR review APPROVED pattern

Check: gh api .../reviews --jq '[.[] | select(.user.login=="coderabbitai[bot]")] | sort_by(.submitted_at) | last | .state' If APPROVED → exit silently.

CR automated verdict as exit signal

When CR's formal state is COMMENTED but CR posted FINAL VERDICT: APPROVE or READY FOR MERGE (dated after latest formal review) → treat as approval, exit silently.

Do NOT loop — sentinel procedure

1. Check ~/.tmp/HOOK_cr_done_<pr> — if exists, print "PR #N MERGED — sentinel exists, hook suppressed", exit HEARTBEAT_OK. No API calls.
2. If not exists: create it (echo '{"pr":N,"reviewDecision":"MERGED","suppressed":true}' > ~/.tmp/HOOK_cr_done_<pr>), exit HEARTBEAT_OK.
3. 3rd fire (sentinel exists): print "Hook re-fire loop" and exit. Do NOT run /harness from within hook.
4. Always check ~/.tmp/HOOK_no_pr_count.json first — if cap reached (>= 2), stop immediately.

Why sentinel files don't stop context-compaction loops

The CR instruction text is re-injected from the agent's compacted session context, not from a hook script. Hook fires → agent responds → compaction re-embeds pattern → next fire → indefinite cycle. Only /clear breaks it. The no-target-PR hard cap is the durable mitigation.

Branch A per-PR counter cap (CR CHANGES_REQUESTED loops)

Problem: If CR posts CHANGES_REQUESTED but never re-reviews after fixes, Branch A fires indefinitely.

CR incremental-mode detection

• If PR head SHA > CR's reviewed commit_sha AND CR posted <!-- Review triggered --> but no new formal review → stuck in incremental mode. Initialize cap at count=1 immediately.
• Also detect null SHA: commit_sha: null → same treatment.
• Compare: gh api repos/OWNER/REPO/pulls/N --jq '.head.sha' vs gh api .../reviews --jq '... | last | .commit_sha'

Counter procedure

CAP_FILE="$HOME/.tmp/HOOK_branchA_${PR}.json"
COUNT=$(jq -r '.count // 0' "$CAP_FILE" 2>/dev/null || echo 0)
jq --argjson c $((COUNT + 1)) -n '{count: $c}' > "$CAP_FILE"

• count >= 2: Stop Branch A. Dismiss stale CR review directly (see below). Post @coderabbitai approve.
• count == 1: Execute normally, warn "Branch A run 1/2".
• count == 0: Execute normally.
• Reset: Delete cap file when CR posts new formal review or PR state changes.

Defense-in-depth

If CR's formal review predates current PR head AND you already posted @coderabbitai all good?, exit silently.

CR auto-pause check

Before waiting for CR response: gh api repos/OWNER/REPO/issues/PR/comments --jq '.[] | select(.user.login=="coderabbitai[bot]" and (.body | contains("Reviews paused"))) | .id'. If returns ID → post @coderabbitai resume first.

CR incremental review stall — STEP 1-4 caveat

The hook's STEP 1-4 assumes CR will post a new formal review as loop-exit gate. Sometimes CR acknowledges with <!-- Review triggered --> without posting formal review. In this state: reviewDecision frozen, gh api .../reviews returns stale review, hook re-executes same Branch A.

Resolution:

1. Verify PR head SHA advanced beyond CR's commit_sha
2. Verify CR acknowledged (look for <!-- Review triggered -->)
3. Check for CR auto-pause (see above)
4. Initialize Branch A cap at count=1
5. After cap reached — dismiss stale review:

# Get latest CR review ID:
gh api repos/OWNER/REPO/pulls/N/reviews \
  --jq '[.[] | select(.user.login=="coderabbitai[bot]")] | sort_by(.submitted_at) | last | {id, state}'
# Dismiss (replace REVIEW_ID):
gh api repos/OWNER/REPO/pulls/N/reviews/REVIEW_ID/dismissals \
  --method PUT -f message="Stale CR verdict — dismissing for fresh re-review" -f event=DISMISS