Add --help flag to CI debugging scripts

Both bin/ci-rerun-failures and bin/ci-run-failed-specs now support --help/-h
flags that display:
- Usage instructions
- Available options
- Examples
- Features
- Related tools

Makes the scripts more discoverable and easier to use for contributors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

bin/ci-rerun-failures

@@ -15,12 +15,48 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# Show help
+show_help() {
+  cat << EOF
+${BLUE}CI Failure Re-runner${NC}
+
+Automatically detects failed CI jobs from GitHub and re-runs them locally.
+
+${YELLOW}Usage:${NC}
+  bin/ci-rerun-failures [OPTIONS] [PR_NUMBER]
+
+${YELLOW}Options:${NC}
+  --previous, --prev, -p    Search recent commits for failures (when current is clean)
+  --help, -h                Show this help message
+
+${YELLOW}Examples:${NC}
+  bin/ci-rerun-failures              # Check current commit
+  bin/ci-rerun-failures --previous   # Find failures in recent commits
+  bin/ci-rerun-failures 1964         # Check specific PR number
+
+${YELLOW}Features:${NC}
+  - Fetches actual CI failures from GitHub using gh CLI
+  - Waits for in-progress CI jobs (polls every 30s)
+  - Maps CI job names to local rake commands
+  - Deduplicates commands
+  - Shows what will run before executing
+
+${YELLOW}Related Tools:${NC}
+  bin/ci-run-failed-specs    Run specific failing RSpec examples
+  bin/ci-local               Smart test detection based on code changes
+EOF
+  exit 0
+}
+
 # Parse arguments
 USE_PREVIOUS=false
 PR_NUMBER=""
 
 while [[ $# -gt 0 ]]; do
   case $1 in
+    --help|-h)
+      show_help
+      ;;
     --previous|--prev|-p)
       USE_PREVIOUS=true
       shift

bin/ci-run-failed-specs

@@ -18,9 +18,62 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# Show help
+show_help() {
+  cat << EOF
+${BLUE}Failed Spec Runner${NC}
+
+Run only the specific RSpec examples that failed in CI.
+
+${YELLOW}Usage:${NC}
+  bin/ci-run-failed-specs [OPTIONS] [SPEC_PATHS...]
+  pbpaste | bin/ci-run-failed-specs
+  bin/ci-run-failed-specs < failures.txt
+
+${YELLOW}Options:${NC}
+  --help, -h    Show this help message
+
+${YELLOW}Examples:${NC}
+  # Pass spec paths directly
+  bin/ci-run-failed-specs './spec/system/integration_spec.rb[1:1:1:1]'
+
+  # Copy from GitHub Actions, paste to run
+  pbpaste | bin/ci-run-failed-specs
+
+  # From file
+  bin/ci-run-failed-specs < failures.txt
+
+  # Multiple specs
+  bin/ci-run-failed-specs './spec/system/integration_spec.rb[1:1:1:1]' './spec/system/integration_spec.rb[10:1]'
+
+${YELLOW}Features:${NC}
+  - Parses RSpec failure output automatically
+  - Extracts spec paths from "rspec ./spec/..." lines
+  - Deduplicates specs
+  - Auto-detects working directory (runs from spec/dummy when needed)
+  - Confirms before running
+
+${YELLOW}Workflow:${NC}
+  1. Go to failed job on GitHub Actions
+  2. Copy the "Failed examples:" section
+  3. Run: pbpaste | bin/ci-run-failed-specs
+  4. Tests run only for those specific failures
+
+${YELLOW}Related Tools:${NC}
+  bin/ci-rerun-failures    Auto-detect and re-run failed CI jobs
+  bin/ci-local             Smart test detection based on code changes
+EOF
+  exit 0
+}
+
 echo -e "${BLUE}=== Failed Spec Runner ===${NC}"
 echo ""
 
+# Check for help flag
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  show_help
+fi
+
 # Collect spec paths
 SPECS=()