---
name: ralph
description: "Autonomous engineer relay for ticketed repos — ticket-file folders (docs/tickets/, docs/changes/, doc/changes/, or doc/tickets/) or GitHub issues (a `.ralph` file with `queue: github-issues`). Picks the next todo ticket/issue, completes it, marks it done, exits. Also loaded for authoring new tickets/issues. Triggers on /ralph and ticket writing in qualifying repos. Do not use without a ticket folder or a `.ralph` queue marker."
argument-hint: "[optional change-file slug]"
---

# Ralph — Change File Relay

You are one engineer in a relay team. Each engineer picks the next change off the stack, completes it, marks it done, and exits so the next engineer can take over. **Do exactly one change and stop.**

## When NOT to Use This

`/ralph` is for **tactical, repo-internal code changes** that do not need human review before shipping — small features, fixes, refactors that can land on main directly. The change marks itself `done` and pushes without ceremony.

Do **not** put work into the ticket folder if any of these are true:

- The output is **client-facing or publishable** (blog posts, newsletters, LinkedIn, emails, proposals) — those need Chris's review before they go out, not autonomous merge. Use a vault project instead.
- The change is **strategic, cross-cutting, or needs Chris's judgement** on direction, scope, or tone — use a vault project + `/worker`.
- The change touches **multiple repos at once** — vault projects coordinate cross-repo work better.
- The repo deploys to **production with no rollback** and the change is non-trivial — prefer a PR Chris can review, not a direct push.
- The ticket has **a UX design component with no artboard behind it** — layout, placement, a new page or flow, an interactive surface. See the next section.

`/ralph` is the right tool when the answer to "would Chris be surprised if I shipped this without asking?" is **no**.

## Pick by surface

Whether a ticket is autonomous depends on **who ends up looking at the output**, not on how hard it is. `/delegate` owns the full rule (SURFACE, copy is not a blocker, the artboard as the entry condition for UX work); load it before deciding. What it means inside a `/ralph` pass:

- A ticket with no human-visible surface, whose acceptance you can prove from here (a test, a curl, a query on live telemetry, a row in a store), is yours. Build it, verify it yourself, close it on green. Never park this class in `qa`.
- A ticket with a UX design component and no artboard is not autonomous work. **Skip it.** If the queue is mostly these, say so in one line rather than picking one anyway. Do not build it and leave it in `qa` for Chris to check later, because every one he opens spawns more tickets.
- Wording alone never parks a ticket and never stops you to ask (Chris, 2026-08-22). Use the artboard's string where one exists, otherwise write the obvious one, ship it, and list the strings you composed in the closing comment. Copy an agent speaks is corrected by evals, not by his eyeball.

`qa` stays the right terminal state only for a surface the agent genuinely cannot drive and did not build interactively.

If the project has its own `RALPH.md` or `AGENTS.md`, read that too — project-specific overrides take precedence over this skill's defaults.

## Queue-specific mechanics

Inspect the repo, then load the matching reference before touching queue state:

- A `.ralph` file containing `queue: github-issues` → read `references/github-issues.md`. When authoring a new issue, also read the writing guidance in `references/ticket-files.md`.
- A file queue under `docs/tickets/`, `docs/changes/`, `doc/tickets/`, or `doc/changes/` → read `references/ticket-files.md`.

The loaded reference owns queue-specific formats and state transitions. Apply its translations wherever the core relay below refers to a ticket file, frontmatter, or editing queue state.

## Decision Precedence

A ticket records the decision at the time it was written; it is not an eternal product contract. Before implementing, search the ticket folder for the same feature/surface and read later tickets, dated notes, and QA outcomes. Apply this order: **the user's current instruction > the newest explicit dated decision or ticket > older ticket prose**. A later ticket may narrow, reverse, or supersede an older ticket even when the older file still says `todo`, `qa`, or `done`; never resurrect the older behaviour just because its acceptance section is more detailed. If the apparent conflict cannot be ordered confidently, ask in an interactive run or record the question and mark the ticket `blocked` in an autonomous run.

Whenever you edit a ticket for any reason, audit its frontmatter before saving. The status must describe the ticket's state **now**, not the state it had when the file was first written: active implementation is `doing`; implemented observable behaviour awaiting a genuinely human-only check is `qa`; accepted or programmatically proven work is `done`; work awaiting an external decision or prerequisite is `blocked`; unstarted approved work is `todo`. Reopening or fixing a failed QA ticket means updating the status as part of the same edit. Never append a result or decision that contradicts the frontmatter and leave the stale status in place.

## On Start

1. **Verify the queue exists and load its reference**: a `.ralph` file declaring `queue: github-issues` uses `references/github-issues.md`; a ticket folder (`docs/tickets/`, `docs/changes/`, `doc/tickets/`, or `doc/changes/`) uses `references/ticket-files.md`. If neither exists, exit immediately with a one-line message — there is nothing to do.
2. **Check git state.** Run `git status` and `git log -1 --oneline`. Note the current branch.
3. **Check CI health on the current branch BEFORE starting new work.** The most recent run must have `conclusion: "success"`. If it is `in_progress` or `queued`, wait for it to finish (`gh run watch <id> --exit-status`) — never start a new change while a previous push is still running. If it is `failure` or `cancelled`, fixing it IS this run's task, and you must watch the fix land green before exiting. See "CI Discipline" below.
4. **Sweep spent delegation worktrees** with `~/.claude/skills/delegate/scripts/sweep_worktrees.sh` (dry run first, then `--yes`), following the ownership rules in `/delegate`. Do it at the start of the run, when nothing of this session is live yet.
5. **Look for a `doing` change first.** Glob the ticket folder's `*.md` files and grep for `^status: doing`. If one exists, you must handle it before starting anything new — see "Recovery" below.
6. **Otherwise pick the best next todo.** Read every ticket file with `status: todo`. Skip `blocked`, `proposed`, and `qa`. Apply **Decision Precedence** by searching for later tickets/notes on the same surface before treating its acceptance text as current. If a spec names a dependency and that dependency is not `done`/`shipped`, skip it. From what is left, pick the ticket that best unblocks downstream work and fits in one bounded run. Alphabetical order is the tiebreaker, not the rule. State your pick plus a one-liner rationale before claiming it.
7. **If an argument was passed**, treat it as a slug/filename hint and pick that specific change instead (still validate it is `todo` or `doing`).
8. **If nothing is pickable and CI is green**, print one line (`No todo changes — nothing to do.`) and exit.

## CI Discipline

Before claiming, confirm the latest run is green. After push, watch the run to completion. If red, fix locally and re-watch — do not exit on a red build. If the repo has no CI, skip. See `references/ci-workflow.md` for the `gh` commands and the red-build recovery checklist.

## Recovery (a `doing` change exists)

A previous engineer claimed a change but did not finish (or you are resuming yourself). Do not assume they got it right.

1. Read the change file in full, including any notes appended at the bottom.
2. Run `git diff` and `git status` to see uncommitted work.
3. Run the project's tests (see "Verify" below).

| Working tree | Tests | What likely happened | Action |
|---|---|---|---|
| Clean | Pass | Finished but did not mark done | Verify the work matches Acceptance, then mark done |
| Clean | Fail | Broke something on the way out | Fix the failing tests, then mark done |
| Dirty | Pass | Mid-flight, healthy | Read the diff, finish what is needed, mark done |
| Dirty | Fail | Mid-flight, broken | Read the change file's notes, fix or redo |

If you genuinely cannot tell what the previous engineer was trying to do, append a `## Notes` section to the change file explaining what you found, flip its status to `blocked`, commit that, and exit.

## Claim the Change

Edit the change file's frontmatter: `status: todo` → `status: doing`. Do **not** commit this on its own — it will be part of the final commit alongside the implementation.

## Do the Work

Follow the project's testing discipline. If `CLAUDE.md` says "write a failing test first", do that. Otherwise default to:

1. **Understand the goal** — what does the user see/experience when this is done? Re-read the Acceptance criteria.
2. **Write a failing test** capturing the acceptance criteria. Use the right test level for the project (unit / integration / e2e).
3. **Make it pass** with the minimal change.
4. **Refactor** for clarity, but do not scope-creep. A bug fix is a bug fix; do not restructure surrounding code.
5. **Stay inside the change.** If you discover unrelated issues, note them in the change file's `## Notes` section or open a new change file with `status: todo`. Do not fix them in this commit.

## Delegate the Build

**Load `/delegate` (Skill tool) before dispatching any worker.** It owns routing, the Codex invocation, worktree isolation and landing, briefing discipline, and verification: a subagent claiming "done" is not evidence, so you re-run the AFFECTED gate yourself. You stay the engineer of record: you pick the ticket, review the returned diff, own commit/push/CI. Delegate only what the surface rule above says is yours to build.

Ralph-specific: **the worker's briefing is the ticket file itself** — point it at `doc/tickets/<file>.md` (or `docs/changes/...`, or the `gh issue view N --comments` output) in its own worktree; never write a parallel plan.md.

## Verify

**Tests passing is not enough.** Verify the actual behaviour works.

Detect the project's commands from `package.json`, `Makefile`, `go.mod` and the like rather than hardcoding a package manager. Run them in parallel where possible. **Every check must be green** before you mark done. If something fails, fix it. Do not skip hooks (`--no-verify`) and do not bypass type checks.

For UI changes, also verify visually if you can (dev server + screenshot via Chrome MCP tools, if available).

### Security-boundary changes — review before marking done

If the change touches a **security boundary** — DB migrations/schema, RLS, auth, access policies, SECURITY DEFINER functions, or membership/permission logic — a green test run is **not** sufficient to mark done. Tests rarely cover what an attacker can reach; they cover what the app does.

Before marking done, do a deliberate security pass: run the four-boundary check (positive / negative / cross-tenant / role-bypass — see global rules), and if the repo has a security gate (an RLS assertion, a policy test, an advisor check), run it locally rather than discovering the failure in CI.

**For any new public-schema table, enable RLS and add a policy (or revoke anon/authenticated).** Postgres defaults RLS to off, so `create table public.x (...)` with no RLS statement is as exposed as an explicit disable. Never pattern-match an RLS-off line from an older migration (airskills, 2026-05-22, `references/gotchas.md`).

## Mark Done

Edit the change file's frontmatter: `status: doing` → `status: done`. Add a `completed:` date line. Optionally append a brief `## Notes` section at the bottom of the file capturing any decisions, gotchas, or follow-ups for future engineers — but keep it terse, the git history is the primary record.

```markdown
---
status: done
title: Add search box to skills dashboard
created: 2026-04-06
completed: 2026-04-06
---
```

**If the project defines a `qa` sign-off gate** (its CLAUDE.md/RALPH.md says so): a slice with a **user-observable surface** (a UI change, an API/message behaviour, anything a human can watch) terminates at **`status: qa`, not `done`** — you have merged it, CI is green, you smoke-tested it, but only the human confirms it live. Add the `completed:` date and a `## QA` section listing the exact steps to verify cold (do *X*, expect *Y*), then leave it for them to flip `qa → done`. A **purely internal** slice (refactor, test plumbing) with no watchable surface still goes straight to `done` — do not invent a QA step that is really "trust CI". So does a slice whose only human-visible part is **wording**: ship it and let a tweak or an eval correct it.

## Commit and Push

Single commit containing both the implementation and the change-file flip. Commit message format:

```
<change title>

Closes <ticket-folder>/<filename> (use the repo's actual path, e.g. doc/tickets/add-search.md).

<one or two sentences on what changed and why>
```

Then push to the current branch. If the branch has no upstream, set it with `-u`.

If pre-commit hooks fail, fix the issue and create a NEW commit (do not `--amend` — see global rules). Do not use `--no-verify`.

## Watch the Build

After every push, watch the run to completion before exiting. If green, mark done and exit. If red, the most common cause is a partial commit — run `git status` first; a dirty tree after your commit means the fix did not actually go in. Otherwise read the failed logs, fix locally, commit (no `--amend`), push, re-watch. Two failed attempts → flip the change to `blocked` with a `## Notes` section. See `references/ci-workflow.md` for `gh` commands, the dirty-tree gotcha in detail, and cross-repo release ordering.

## When You Need to Ask

Do not guess when the change is ambiguous. If acceptance criteria are unclear, there is a real decision Chris needs to make, or you would be inventing product behaviour, stop and get an answer. **Wording is not product behaviour** — write the string and move on (see Pick by surface above).

How you surface the question depends on whether a human is watching:

- **Interactive session** (you can see the user's prompt in this conversation): just ask, and wait for the reply. Do not mark the change blocked — you are still actively on it.
- **Autonomous session** (invoked via `ralph.sh`, `/worker`, cron, or any unattended run): nobody is there to answer. Append a `## Questions` section to the change file listing what you need decided (with enough context that Chris can answer cold), flip status to `blocked`, commit the change file alone, and exit. The next interactive pass can unblock it.

Heuristics for detecting autonomous mode: you were triggered without a fresh user message in this turn, or the surrounding instructions include `ralph.sh`, `worker`, cron, or `autonomous`. When in doubt, write the question to the file — a noisy question to an absent user is wasted.

## If You Get Stuck

If the change is unclear, the tests are unfixable, or you are hitting repeated permission errors:

1. Append a `## Notes` section to the change file describing what you tried and what you need decided.
2. Flip status to `blocked`.
3. Commit the change file alone (no implementation).
4. Exit with a one-line message explaining what you need.

## Scope Discipline

- One change per run. Always.
- Do not open the change file, get partway, and start poking at unrelated code. The next engineer will pick up the next item.
- Do not refactor surrounding code "while you're here".
- **Build the whole ticket in one run, and a big ticket is still just a ticket** (Chris, 2026-07-08 and 2026-07-29, `references/gotchas.md`). Do not split because of context size, and do not propose a design doc first: touching a dozen files or standing up a new subsystem earns no separate planning artifact. Write the problem, the boundary, and the acceptance well enough to build from, then build it.
- Only split if a ticket is genuinely too large even for that (rare — a sprawling migration, dozens of files). If you do split, write a new change file for each chunk, mark the original one `done` with a note explaining the split, then exit.

## Bundled Runner

`ralph.sh` spawns one engineer session per ticket and streams its output. Run `~/.claude/skills/ralph/ralph.sh --help` for its iteration, harness, and free-text steering options.

The runner detects the four supported ticket-folder names. When none exists at the current root, it descends one level only if exactly one immediate subdirectory has a ticket folder; this supports monorepos without guessing between several candidates.

#!/bin/bash

# Ralph Loop - Autonomous engineer relay
# See --help for usage.

set -e

# Track claude PID so we can kill it on Ctrl-C
CLAUDE_PID=""
cleanup() {
    echo -e "\n${RED}✗${NC} Interrupted"
    [ -n "$CLAUDE_PID" ] && kill "$CLAUDE_PID" 2>/dev/null
    exit 130
}
trap cleanup INT TERM

# ANSI colours
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
DIM='\033[2m'
NC='\033[0m' # No colour

print_help() {
    cat <<'EOF'
Ralph Loop — autonomous engineer relay.

Usage:
  ralph.sh [OPTIONS] [INSTRUCTIONS...]

Options:
  -h, --help              Show this help and exit.
  -n, --iterations N      Maximum loop iterations (default: 10).
      --harness NAME      Which CLI to spawn per iteration:
                            claude (default) — uses Claude Code with
                              stream-json output and pretty per-tool
                              formatting.
                            codex            — uses OpenAI Codex CLI
                              (`codex exec`), raw output streamed.
                            pi               — uses the pi coding
                              assistant (`pi --print`), raw output
                              streamed.

Arguments:
  INSTRUCTIONS            Free-text instructions appended to every harness
                          invocation in this run. All non-flag arguments
                          after options are joined with spaces and included
                          verbatim in the prompt. Use this to steer focus
                          ("only touch the CLI", "keep changes small", etc.)
                          without editing the ticket files.

Queue discovery:
  If the current directory has a `.ralph` file containing
  `queue: github-issues`, the repo's GitHub issues are the queue (needs
  the `gh` CLI, authed). Open unlabelled issues are the todo stack;
  `doing`/`qa`/`blocked`/`proposed` labels carry the workflow state.

  Otherwise ralph looks for a ticket folder in this order, in the
  current directory:
    docs/tickets/  docs/changes/  doc/changes/  doc/tickets/
  If none is found in the current directory, it scans IMMEDIATE
  subdirectories one level down for the same folder names. If exactly one
  subdirectory has a ticket folder, ralph cd's into that subdirectory and
  operates from there. If multiple subdirectories qualify, ralph lists
  them and exits — cd into the specific subproject yourself.

  Falls back to beads if `.beads/` is present and `bd` is on PATH.

Examples:
  ralph.sh                                 # 10 iterations, claude harness
  ralph.sh -n 100                          # 100 iterations
  ralph.sh 100                             # same (backwards-compat shorthand)
  ralph.sh focus on the auth code          # default iterations, focused steer
  ralph.sh -n 50 keep changes small        # both
  ralph.sh --harness codex                 # use OpenAI Codex CLI
  ralph.sh --harness pi -n 20              # use pi, 20 iterations
EOF
}

# ---- Parse args -----------------------------------------------------------

MAX_ITERATIONS=10
EXTRA_INSTRUCTIONS=""
HARNESS="claude"
POSITIONAL=()

# Watchout threshold on the opt-in `qa` column: once this many tickets await a
# human's sign-off, ralph warns loudly (so the backlog gets cleared) but keeps
# working — a nudge, not a hard gate. Override with QA_WIP_WATCHOUT.
QA_WIP_WATCHOUT="${QA_WIP_WATCHOUT:-5}"

while [ $# -gt 0 ]; do
    case "$1" in
        -h|--help)
            print_help
            exit 0
            ;;
        -n|--iterations)
            if [ -z "${2:-}" ]; then
                echo -e "${RED}✗${NC} $1 requires a value" >&2
                exit 2
            fi
            MAX_ITERATIONS="$2"
            shift 2
            ;;
        --harness)
            if [ -z "${2:-}" ]; then
                echo -e "${RED}✗${NC} --harness requires a value (claude|codex|pi)" >&2
                exit 2
            fi
            HARNESS="$2"
            shift 2
            ;;
        --)
            shift
            POSITIONAL+=("$@")
            break
            ;;
        *)
            POSITIONAL+=("$1")
            shift
            ;;
    esac
done

case "$HARNESS" in
    claude|codex|pi) ;;
    *)
        echo -e "${RED}✗${NC} unknown harness: $HARNESS (expected: claude, codex, pi)" >&2
        exit 2
        ;;
esac

if ! command -v "$HARNESS" &>/dev/null; then
    echo -e "${RED}✗${NC} harness binary '$HARNESS' not on PATH" >&2
    exit 2
fi

# Backwards-compat: a single purely-numeric positional arg is iterations.
if [ "${#POSITIONAL[@]}" -eq 1 ] && [[ "${POSITIONAL[0]}" =~ ^[0-9]+$ ]]; then
    MAX_ITERATIONS="${POSITIONAL[0]}"
elif [ "${#POSITIONAL[@]}" -gt 0 ]; then
    EXTRA_INSTRUCTIONS="${POSITIONAL[*]}"
fi

if ! [[ "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
    echo -e "${RED}✗${NC} iterations must be a positive integer (got: $MAX_ITERATIONS)" >&2
    exit 2
fi

# ---- Locate the ticket folder --------------------------------------------

TICKET_DIRS=("docs/tickets" "docs/changes" "doc/changes" "doc/tickets")

find_tickets_in() {
    # Echo the first matching ticket dir under $1, or nothing.
    local base="$1"
    local d
    for d in "${TICKET_DIRS[@]}"; do
        if [ -d "$base/$d" ]; then
            echo "$d"
            return 0
        fi
    done
    return 1
}

ITERATION=0
START_DIR="$PWD"
PROJECT_DIR="."   # relative to START_DIR; "." means tickets are at the top level
MODE=""

# GitHub-issues queue: an explicit `.ralph` marker file opts the repo in.
if [ -f .ralph ] && grep -qE '^queue:[[:space:]]*github-issues[[:space:]]*$' .ralph; then
    if ! command -v gh &>/dev/null; then
        echo -e "${RED}✗${NC} .ralph declares queue: github-issues but 'gh' is not on PATH" >&2
        exit 2
    fi
    MODE="github"
fi

TICKETS_DIR=""
if [ -z "$MODE" ]; then
    TICKETS_DIR=$(find_tickets_in ".") || true
fi

if [ -z "$MODE" ] && [ -z "$TICKETS_DIR" ]; then
    # Try one level down. Collect every subdirectory that has a ticket folder.
    # We DO NOT cd into the subdir — staying in $START_DIR keeps the harness's
    # trust boundary (claude --permission-mode acceptEdits, codex --add-dir)
    # rooted at the parent so sibling repos in a monorepo-style layout
    # (e.g. airskills/platform + airskills/cli) are both writable. The engineer
    # is told via the prompt where the project and ticket folder actually live.
    CANDIDATES=()
    for sub in */; do
        [ -d "$sub" ] || continue
        if found=$(find_tickets_in "${sub%/}"); then
            CANDIDATES+=("${sub%/}|$found")

# CI Workflow Mechanics

How `/ralph` interacts with GitHub Actions CI — the pre-claim health check and the post-push watch.

The principle: a push that hasn't been verified on CI is not "done". Local greens don't prove the change passes the CI environment (different Node version, missing env vars, stricter linting). Ralph is responsible for **landing green**, not just pushing.

## CI Health Check (before claiming any change)

Before picking up a new todo, confirm the current branch's CI is green.

```bash
# Resolve the remote and branch
REMOTE=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+/[^/]+)\.git$|\1|; s|\.git$||')
BRANCH=$(git branch --show-current)

# Get the latest run for this branch. -R disambiguates when there are
# multiple remotes, --branch scopes to the current branch only.
gh run list --branch "$BRANCH" --limit 1 --json status,conclusion,databaseId,name
```

Outcomes:

- **`conclusion: "success"`** — CI is green. Proceed to pick the next change.
- **`status: "in_progress"` or `"queued"`** — the previous push is still running. **Wait for it.** Watch with `gh run watch <id> --exit-status` until it completes. Do NOT start a new change while a previous run is in flight — your work would land on top of an untested base and you have no way to tell which push broke things if CI flips red. On success, proceed. On failure, fix as below.
- **`conclusion: "failure"` or `"cancelled"`** — CI is red. Your job for this run is to fix it. Read the failed logs (`gh run view <id> --log-failed`), fix the underlying cause locally, run the same checks that failed, commit, push, and then **watch the new run to completion with `gh run watch <new-id> --exit-status`**. If the new run is green, exit (the next ralph instance picks up the next todo). If the new run is still red, repeat — fix, push, watch. **Never pick a new todo change while CI is red or a fix attempt is in flight.** Pushing a speculative fix and exiting without watching it land is not sufficient — the next ralph run must see a *green* conclusion on the most recent run before it is allowed to claim new work. If you've tried twice and still can't get it green, stop and set `status: blocked` on the relevant change with a note for Chris.
- **No runs at all** — nothing to watch; proceed.

If the repo has no CI configured (no `.github/workflows/`, no Cloudflare deploy config, etc.), skip the CI health check — local verification is the bar.

## Watch the Build (after every push)

Always watch the run triggered by your push and react to the result before exiting.

```bash
# Immediately after git push succeeds:
# Find the run your push triggered. `--branch` + `--limit 1` gets the
# latest for the current branch, which is almost always yours (racy
# only if another engineer pushes in the same second).
RUN_ID=$(gh run list --branch "$(git branch --show-current)" \
  --limit 1 --json databaseId --jq '.[0].databaseId')

# Block until the run finishes. --exit-status makes failed runs return
# non-zero so the CLI short-circuits properly.
gh run watch "$RUN_ID" --exit-status
```

**Doc-only pushes may trigger no run — don't block waiting for one.** Many repos
scope CI with `paths-ignore` (e.g. `doc/**`, `docs/**`, `*.md`). A commit that
*only* flips a ticket's status flag (a recovery close, or filing a new ticket)
touches nothing but the ticket markdown, so CI is skipped by design and no run
ever appears. Before watching, sanity-check what you actually changed: if the
commit is doc-only, confirm the push reached the remote (`git ls-remote origin
<branch>`) and exit — there is nothing to watch. Polling for a run that will
never start just wastes the run.

Outcomes:

- **Green.** Print one-line success, mark the change done if not already, exit.
- **Red.**
  1. **First, run `git status`.** If the working tree is dirty, a previous session (or your own earlier edits) may have left the fix uncommitted. `git diff origin/main` shows exactly what isn't on the remote — that diff may BE what CI is missing. Do NOT start diagnosing a "new" failure before ruling this out. This is the single most common cause of "CI keeps failing even though I fixed it locally": the commit didn't include all the code that made local tests pass. If the diff looks like the fix, stage it, commit, push, re-watch.
  2. Pull the failed logs: `gh run view "$RUN_ID" --log-failed`.
  3. Understand the failure. Don't panic-revert.
  4. Fix it locally. Run the equivalent command yourself before trusting the fix (e.g. if CI's `npx next build` failed, run it locally).
  5. Commit the fix as a new commit (not --amend; global rule).
  6. **Before pushing, run `git status` again — working tree MUST be clean.** A dirty tree after the commit means the commit is partial; the rest will disappear from context when this session ends, and CI will be red for "no reason" next cycle. If you have intentional uncommitted work, stash it before pushing the fix and evaluate whether it should be in this commit.
  7. Push and repeat the watch. Ralph is responsible for landing green, not just pushing.
  8. If you can't fix it in this run, append a `## Notes` section to the change file with what went wrong + what you tried, flip its status to `blocked`, commit, push the block, and exit. Don't leave a red build unexplained.
- **Timeout / watch errors.** `gh run watch` can occasionally misbehave. Fall back to polling: `gh run view "$RUN_ID" --json status,conclusion` in a short loop. Do not use `sleep` loops without a bound — cap at ~20 minutes; if CI takes longer than that for a typical change, something else is wrong and Chris needs to see it.

## Cross-repo releases

When platform depends on a tagged CLI release: follow the specific order captured in the repo's CLAUDE.md (typically tag and release the CLI first, wait for its release workflow to publish, only then push the platform). Watch BOTH runs. Don't push the second repo until the first is green.

# Ralph GitHub Issues mode

Read this reference when a repo's `.ralph` file contains `queue: github-issues`. Apply these translations wherever the main skill refers to a ticket file, frontmatter, or editing queue state.

An open issue with no workflow label is the todo stack:

| File mode | GitHub mode |
|---|---|
| `status: todo` | open issue, no workflow label |
| `status: doing` | open + `doing` label |
| `status: qa` | open + `qa` label |
| `status: blocked` | open + `blocked` label |
| `status: proposed` | open + `proposed` label |
| `status: done` | closed as completed |
| `status: superseded` | closed as not-planned, `superseded` label |

Operations translate mechanically:

- Claim: `gh issue edit N --add-label doing`, then comment with the selection rationale.
- Append `## Notes` or `## Questions`: comment on the issue.
- Scan: `gh issue list --state open --json number,title,labels`; skip `qa`, `blocked`, and `proposed`. Handle an open `doing` issue first as the recovery case.
- Precedence search: `gh issue list --state open --search '<terms>'`; open closed issues only to trace what shipped.
- File a new ticket: `gh issue create` with the same problem-first body described in `ticket-files.md`. Use `-l proposed` only for the narrow approved use of that state.

## Behaviour specific to issues

- **Pass every comment body with `--body-file`, never an inline `--body`.** A double-quoted `--body` executes backticks, so quoted code silently vanishes while the command reports success (2026-09-04, `gotchas.md`). Write the body to a scratchpad file with a quoted heredoc (`<<'EOF'`). Repair an affected comment with `gh issue comment --edit-last --body-file`.
- **Comments make progress visible.** Post a claim comment, decisions or gotchas as they happen, and a completion comment stating what you verified, including test names or commands and the commit SHA.
- **Commits reference the issue.** Use `Closes #N` in the commit body when the commit completes the work; GitHub closes it when the push lands on the default branch. Drop the `doing` label after pushing. Use `Refs #N` when the slice terminates at `qa` or the commit is partial.
- **At the qa gate:** swap `doing` to `qa`, post the `## QA` steps as a comment, leave the issue open, and commit with `Refs #N`. Only the human closes a `qa` issue or returns it to todo after a failed check.
- **When blocked:** swap the label to `blocked` and comment with the exact missing input. There is no separate change-file commit.
- **When delegating:** the issue and its comments are the worker briefing. Give the worker `gh issue view N --comments` output, or have it run that, instead of writing a parallel plan.

# Ralph gotchas — the stories behind the one-line rules

Each rule in `SKILL.md` that cites this file has its incident here. Read the entry when you want to know why the rule is shaped the way it is.

## `gh --body` executes backticks (2026-09-04)

A shell double-quoted `--body` string runs anything inside backticks as a command. A comment quoting `console.warn(\`calendar chat read failed: ...\`)` posted as `console.warn()`, and `command not found` scrolled past in the output while `gh` reported success. Inline code spans and fenced blocks are exactly what an issue comment is for, so this bites on the most valuable comments. Write the body to a scratchpad file with a quoted heredoc (`<<'EOF'`) and pass `--body-file`. `gh issue comment --edit-last --body-file` repairs one already posted.

## The `proposed` pile has no consumer (27agents, 2026-08-23)

Measured on 27agents: 19 of 47 open issues were `proposed`, seven of them 24 days old, and across the repo's whole history exactly three had ever left that pile. Opened-versus-closed over three weeks was 147 to 129, and the +18 was almost exactly the size of the pile. `todo`, `blocked` and `qa` were flat. The queue was not growing because bugs outpaced fixes. It grew because the agent filed suggestions. Labelling a confirmed defect `proposed` is not caution; it files a real bug somewhere nobody looks.

## 33 worktrees (27agents, 2026-08-07)

A repo reached 33 delegation worktrees before anyone noticed, 24 of them shadow arms going back three weeks. Shadows never land, so a cleanup habit tied to landing never fires for them. Sweeping at the start of a run works because nothing of the current session is live yet; at the end, attention has already moved to the result. `/delegate` owns the sweep script and its ownership rules.

## Migration 046 shipped with RLS disabled (airskills, 2026-05-22)

An autonomous `/ralph` run created the airskills OAuth tables and shipped them with row-level security disabled, exposing refresh tokens and auth codes to anyone with the anon key for four days. It copied an older migration's `disable row level security` line without registering that the tables sit in the `public` schema, which PostgREST exposes to `anon` and `authenticated`, and it never opened the adjacent migration that documented this exact fix. Postgres defaults RLS to off on new tables, so a `create table public.x (...)` with no RLS statement is just as exposed as an explicit disable.

## Whole tickets, no design-doc step (Chris, 2026-07-08 and 2026-07-29)

Defaulting to a split because of context size produced confusing partial-done tickets that were hard to track. Current context windows have room for a well-scoped ticket end to end, so build the whole ticket in one run (2026-07-08).

Touching a dozen files or standing up a new subsystem does not earn a separate planning artifact first. Current models hold the design and the implementation in one run, so a preceding design doc buys ceremony, not information. Do not propose one, and do not tell Chris a ticket is "spec-sized" (2026-07-29).

# Ralph ticket-file queues

Read this reference before inspecting, claiming, updating, or authoring a file-based Ralph ticket.

## Change file format

Changes live as markdown files in the repo's ticket folder — `docs/tickets/`, `docs/changes/`, `doc/tickets/`, or `doc/changes/` (first one that exists wins) — with YAML frontmatter:

```markdown
---
status: todo
title: Add search box to skills dashboard
created: 2026-04-06
---

# What

One paragraph describing what the user should see when this is done.

# Why

Optional context — link to the request, ticket, or rationale.

# Acceptance

- Bullet list of concrete acceptance criteria
- Anything that must hold true before this can be marked done
```

**Status values:**
- `todo` (aliases: `draft`, `pending`) — ready to pick up
- `doing` (alias: `in-progress`) — claimed by an engineer (you, or a previous one who did not finish)
- `qa` — **(opt-in; only where a project's CLAUDE.md/RALPH.md defines a sign-off gate)** code-complete + CI-green + self-verified, but awaiting a human's live eyeball. **Never pick a `qa` file** (treat it exactly like `done` — the code is already on main, so nothing downstream is blocked); only the human flips `qa → done`, or back to `todo` on a failed check. See "Mark Done" in the main skill for when to terminate a slice at `qa` instead of `done`. If a stack builds up in `qa` (3-5+), flag it loudly so the human clears the backlog, but keep pulling `todo` work.
- `done` (aliases: `shipped`, `complete`) — complete
- `blocked` — **agreed** work that cannot proceed until Chris supplies something concrete (a credential, a console step, an external reply); skip. Name the missing input in the ticket so he can unblock it cold — it flips back to `todo` the moment the input exists.
- `proposed` — an **idea Chris has not agreed to build**; skip. Whether to do it at all is his open call. It graduates to `todo` only when he says yes, or gets deleted when he says no. A `blocked` queue is work waiting on config; a `proposed` pile is decisions waiting on judgement.

Prefer the canonical values (`todo`, `doing`, `done`, `blocked`, `proposed`; plus `qa` where a project defines a sign-off gate) when writing new files. Aliases exist so projects that use existing spec conventions (e.g. `status: draft` → `status: shipped` in long-form design docs) can be picked up without renaming everything. When editing a change file, keep its existing vocabulary.

**Filename convention:** Alphabetical sort is the default order when specs are otherwise equal. Dated prefixes (`2026-04-06-add-search.md`) work well; numeric prefixes (`001-foo.md`) also work. Scan the whole queue and pick the best next instead of blindly taking the first alphabetical. Weigh explicit dependencies, blast radius, and what unlocks downstream work. Say one line about why you chose the ticket when you claim it.

## Writing new change files

A ticket describes the **problem to solve**, leaving implementation decisions to the engineer who picks it up with fresh eyes and current code.

- **Capture the essence of the problem.** What is broken, missing, or wrong? Why does it matter? Keep it short.
- **Bugs:** include repro steps, expected versus actual behaviour, and a vague pointer at where the problem likely lives. Repro lets the engineer write a failing test and confirm the fix.
- **Features:** write acceptance criteria as observable behaviour.
- **Leave out code diffs, prescribed error codes, exact function signatures, full tests, and step-by-step patches.** If you know the fix that precisely, do the work instead of filing a ticket for it.
- **Defer decisions that will be better-informed at build time.** Dependency versions, model choices, and fast-moving SDK details are most accurate at pickup. State the direction and constraint; pin only what is settled. Name important unknowns instead of guessing.

Belongs in the ticket: user-visible problem, repro, acceptance, non-obvious constraints, and a vague pointer at the starting surface.

If you find yourself writing out the solution, stop — either do the work now or file a much thinner ticket.

**Do not file your own ideas as tickets, and pick the honest status when filing.** `proposed` has no consumer, so it only grows (27agents, 2026-08-23, `gotchas.md`). A defect you have confirmed in the code is `todo`. Something Chris explicitly asked for is `todo` (or `blocked` if it needs his config first, naming what is missing). Say an unapproved idea in the session rather than filing it; reserve `proposed` for a genuine build-or-remove decision that belongs to Chris and has work waiting on it. Close proposals that have sat unread for weeks as not-planned.