fix: add CI check retry logic to prepare-release script (#337)

The `gh pr checks --watch` command fails immediately when CI checks
haven't registered yet after PR creation. Add a retry loop (5 attempts,
15s between) that detects "no checks reported" and waits. Also update
the skill docs with benchmark timing data (mean 10.3 min across 10
releases) and background mode requirement.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: erraggy

.claude/scripts/prepare-release.sh

@@ -219,8 +219,26 @@ echo ""
 if [[ "$SKIP_TO_CHECKOUT" == "false" ]]; then
     # Step 5.3: Wait for CI and merge
     echo "Step 5.3: Waiting for CI checks..."
-    if ! gh pr checks "$PR_NUMBER" --watch --fail-fast; then
-        echo "Error: CI checks failed for PR #$PR_NUMBER" >&2
+    # CI checks need time to register after PR creation. Retry until checks appear.
+    CI_PASSED=false
+    for attempt in 1 2 3 4 5; do
+        if gh pr checks "$PR_NUMBER" --watch --fail-fast 2>/dev/null; then
+            CI_PASSED=true
+            break
+        fi
+        # If checks haven't appeared yet, wait and retry
+        CHECKS=$(gh pr checks "$PR_NUMBER" 2>&1 || true)
+        if echo "$CHECKS" | grep -q "no checks reported"; then
+            echo "  Checks not yet reported, waiting 15s (attempt $attempt/5)..."
+            sleep 15
+        else
+            # Checks appeared but failed
+            echo "Error: CI checks failed for PR #$PR_NUMBER" >&2
+            exit 3
+        fi
+    done
+    if [[ "$CI_PASSED" != "true" ]]; then
+        echo "Error: CI checks never appeared for PR #$PR_NUMBER after 75s" >&2
         exit 3
     fi
     echo "  ✓ CI checks passed"

.claude/skills/prepare-release/SKILL.md

@@ -137,22 +137,25 @@ After all agents complete:
 
 > ⚠️ **CRITICAL:** Use the prepare script. Do NOT run these commands manually.
 
-After all agent work is committed, from the repository root run:
+After all agent work is committed, from the repository root run the script **in background mode** (`run_in_background: true`):
 
 ```bash
 .claude/scripts/prepare-release.sh <version>
 ```
 
+> **Timing:** The script takes ~13-15 minutes total (CI benchmarks ~10.3 min + CI checks ~3 min + overhead). This exceeds the Bash tool's 10-minute max timeout, so it **must** run in background mode. Use `TaskOutput` with `block: true, timeout: 600000` to wait, and re-check if it times out — the script is idempotent and can be re-run safely.
+
 The script handles:
 
 - **Phase 4:** Push branch, trigger CI benchmarks, wait for completion, pull results
-- **Phase 5:** Create PR, wait for CI checks, merge with `--admin`, switch to main
+- **Phase 5:** Create PR, wait for CI checks (with retry for check registration delay), merge with `--squash --admin`, switch to main
 - **Phase 6:** Generate release notes, save to temp file, display for review
 
 If the script fails partway through, check the error message. You can re-run safely:
 
 - `--skip-benchmarks` flag if benchmarks already completed
 - The script auto-detects already-merged PRs and skips to checkout
+- CI check registration delay is handled with automatic retries (up to 75s)
 
 ### Phase 6.2: Enhance Release Notes
 
@@ -264,4 +267,6 @@ If user chooses "Yes", from the repository root run:
 - CI benchmarks run on the pre-release branch and are included in the PR
 - Document all new public API in CLAUDE.md
 - **ALWAYS use scripts** for phases 4-6 - never run release commands manually
+- **ALWAYS run scripts in background mode** - the prepare script takes ~13-15 min (exceeds Bash 10-min max timeout)
 - **ALWAYS enhance release notes** (Phase 6.2) - never skip to publishing with auto-generated notes only
+- **If the script fails at Phase 5.3** (CI checks), it's often a timing issue — re-run the script (it's idempotent) or manually run `gh pr checks <PR#> --watch` then merge