From 574bd12c6465f6204c3b1540050bd36999456282 Mon Sep 17 00:00:00 2001
From: Paul O'Reilly <hello@pauloreilly.nz>
Date: Sun, 17 May 2026 18:06:58 +1200
Subject: [PATCH] feat: add scan-ralph skill for polling ralph_code overnight
 results

Wraps scripts/scan-ralph-candidates to inject scan output at load time.
Shows unmerged agent-fork branches with changed files and inferred spec IDs.
Designed for /loop 5m /scan-ralph continuous polling.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/scan-ralph/SKILL.md | 82 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 skills/scan-ralph/SKILL.md

diff --git a/skills/scan-ralph/SKILL.md b/skills/scan-ralph/SKILL.md
new file mode 100644
index 0000000..3a89e1c
--- /dev/null
+++ b/skills/scan-ralph/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: scan-ralph
+description: >
+  Scan agent-fork branches for unmerged implementations from ralph_code overnight runs.
+  Reports changed files and inferred spec IDs. Use with "/loop 5m /scan-ralph" to poll
+  continuously for new work.
+allowed-tools: Read, Edit, Bash(git *), Bash(python3 *), Bash(scripts/scan-ralph-candidates *), Bash(grep *), Bash(date *)
+---
+
+# /scan-ralph
+
+<command-name>scan-ralph</command-name>
+
+You are reporting on unmerged implementations from overnight ralph_code agent runs.
+
+## Pre-gathered context
+
+### Scan timestamp
+!`date +"%Y-%m-%d %H:%M"`
+
+### Candidate branches (fetched from agent-fork now)
+!`scripts/scan-ralph-candidates 2>&1`
+
+### Recent main commits (last 5)
+!`git log --oneline -5 main 2>/dev/null`
+
+---
+
+## Instructions
+
+### Step 1: Check scan output
+
+The "Candidate branches" block above contains either:
+
+- Lines of the form `=== task-<uuid> ===` followed by file paths and spec IDs
+- Or the message "No unmerged candidate branches found..."
+
+If the scan failed (e.g. "not in a git repository" or a Python traceback), report the error
+and stop. The user should `cd` into the `agent-runtimes` repo first.
+
+### Step 2: Report results
+
+**No candidates:**
+> No new implementations found. All recent agent-fork branches are already merged or empty.
+
+**Candidates found** — present as a compact list:
+
+```
+Branch: task-<uuid>
+  path/to/file.py  →  SPEC-ID, SPEC-ID
+```
+
+Then say: "**N branch(es) with unmerged implementations found.**"
+
+### Step 3: Suggest next action
+
+If candidates exist:
+> To integrate, follow the workflow in `prompts/ralph_integration.md`.
+> Start with the branch covering the highest-priority spec IDs.
+>
+> Quick recap:
+> 1. `git checkout agent-fork/task-XXXX -- path/to/file.py`
+> 2. Run the xfail test: `python -m pytest tests/test_foo.py::test_bar -v`
+> 3. If XPASS(strict): remove the `@pytest.mark.xfail` decorator, commit
+>
+> Run `/scan-ralph` again after each integration to see the updated candidate list.
+
+If no candidates:
+> Run `scripts/scan-ralph-candidates --hours 168` to look back 7 days if you expect
+> more results, or check `git fetch agent-fork` ran successfully.
+
+---
+
+## Loop usage
+
+This skill is designed for:
+```
+/loop 5m /scan-ralph
+```
+
+Each firing re-fetches `agent-fork` and rescans, so new overnight branches appear
+automatically without manual intervention.