ralph-plot-sprint

One iteration of an automated sprint run driven by ralph-sprint.sh.

Input: $ARGUMENTS = <slug> [AUTOMERGE=true|false]

Parse $ARGUMENTS :

• First word → <slug> (required)

• AUTOMERGE=true anywhere → merge PRs after finalizing; default false

Step 0: Orient

Read the sprint state before deciding what to do. This step always runs.

Get sprint status

/plot-sprint <slug>

Check open PRs

gh pr list --state open --json number,title,headRefName,baseRefName,isDraft
--jq '.[] | "(.number) (if .isDraft then "DRAFT" else "READY" end) (.headRefName) (.title)"'

Read the project's Definition of Done if it exists:

cat docs/definition-of-done.md 2>/dev/null || echo "(no DoD file)"

Build a state summary:

Check Command Result

Unchecked items grep - [ ] in sprint file List or "none"

Open PRs gh pr list --state open

List or "none"

Failing CI gh pr checks <n> per open PR List or "all green"

Unresolved comments gh api ...pulls/<n>/comments per open PR List or "none"

Missing demos compare sprint code items to ls docs/demos/

List or "all present"

RC tag git tag --list 'v*-rc*'

Tag or "none"

For sprints with more than 3 open PRs: use parallel subagents to gather CI and review status. Launch one Task agent per PR with the prompt below, collect all results before proceeding:

Check PR #<N> in repo <owner/repo>:

1. Run: gh pr checks <N> --repo <owner/repo> Return: "CI: pass" or "CI: fail — <failing check names>"
2. Run: gh api repos/<owner/repo>/pulls/<N>/reviews and: gh api repos/<owner/repo>/pulls/<N>/comments Return: "reviewed: yes" or "reviewed: no", "unresolved: <count>"
3. Check sprint item annotation for review_sha: Return: "SHA changed since review: yes/no"

After orienting, decide which steps apply this iteration:

• If open PRs exist → start at Step 1

• If unchecked sprint items exist (no open PR yet) → go to Step 3

• If missing demos → go to Step 5

• If RC tagged but commits exist after latest RC tag (git log $(git tag -l 'v*-rc*' --sort=-v:refname | head -1)..HEAD --oneline | head -1 ) → go to Step 6 (re-tag)

• If RC not yet tagged → go to Step 6

• Otherwise (no open PRs, no unchecked items, demos present, RC tagged, no post-RC commits) → output BLOCKED (sprint is complete pending human testing)

Step 1: Fix CI and Unresolved Comments

For each open PR with failing CI or unresolved review comments:

Failing CI:

• gh pr checks <n> to identify failing checks

• gh pr diff <n>

• read error output to understand the failure

• Fix the underlying code issue, push

• Reply to any related review comments explaining the fix

Unresolved comments:

• gh api repos/<owner>/pulls/<n>/comments to list open threads

• For each: read the comment, fix the underlying issue in code

• Push the fix

• Reply to the comment explaining what was done

• Resolve the thread: gh api repos/<owner>/pulls/<n>/comments/<id> --method PATCH -f body="Resolved in <sha>"

Retry transient failures (network, flaky tests) up to 3 times before marking as blocked.

Step 2: Finalize Ready PRs

Finalize PRs that have: green CI + zero unresolved comments + at least one prior review.

Order matters: finalize PRs whose base branch is main first. For PRs based on other feature branches, wait until that base branch is merged, then rebase.

Mark draft → ready

gh pr ready <n>

If AUTOMERGE=true:

gh pr merge <n> --squash

After merging a base-branch PR, rebase PRs that depended on it:

git fetch origin git checkout <dependent-branch> git rebase origin/main git push --force-with-lease

If AUTOMERGE=false: mark ready and stop — leave merging for the human.

If AUTOMERGE=false and all open PRs are already READY + green CI + reviewed (no drafts, no failing CI, no unresolved comments, no new commits since last review): output BLOCKED — no further automation is possible until the human merges.

Step 3: Build One Sprint Task

If work remains in the sprint (unchecked items with no open PR), implement the highest-priority unblocked item.

Rules:

• At most ONE new task per iteration (steps 1-2 and 4 apply to all PRs; this step is singular)

• Before implementing: search the codebase — do not assume functionality is missing

• Plan-backed items ([slug] notation): check if the plan is approved; if not, run /plot-approve or output BLOCKED

• Plan-only items (no implementation needed, just docs): mark complete on main without a PR — NEVER create feature/* for plan-only work

• Substantial new tasks with no plan: use /plot-idea first

• Small tasks (docs, config, minor fixes): implement directly

Implement → run tests and type-check → create PR with changeset if user-facing.

Step 4: Self-Review Unreviewed Code PRs

Review open PRs that have NO review comments at all. PRs with existing comments (even all resolved) count as already reviewed.

Skip review if:

• PR already has any review comments (resolved or open)

• review_sha annotation matches current HEAD SHA of the branch (no new commits)

• PR contains only docs/plans/ files (plan-only — do a single light factual check instead)

• PR status annotation shows merged

For code PRs: use /pr-review-toolkit:review-pr . Post each finding as an individual PR review comment via gh api . Be specific and harsh — vague comments waste iterations.

Do NOT fix findings in this step — post only. Fixing is Step 1 of the next iteration.

After reviewing: update the sprint item annotation with review_sha and reviewed_at .

Step 5: Create Missing Demos

For each merged code feature without a demo in docs/demos/ :

Identify plan-only items — these do NOT need demos:

• Sprint items annotated status: merged with a docs/plans/ PR (no implementation code)

• Items explicitly marked plan-only in the sprint file

For each code feature needing a demo:

• Use /show-your-work to create the demo

• The demo must include:

• What the feature does

• Evidence it works (test output, command output, config snippet)

• If docs/definition-of-done.md has specific requirements for this feature type, follow them

• Commit to main with message D demo: <feature-name>

Up to 2 demos per iteration — avoids context overload for complex features.

Check after creating: are all code features now covered? If yes, proceed to Step 6.

Step 6: Tag RC Release

When all code features have demos (verify by comparing sprint items to docs/demos/ ):

/plot-release rc

This determines the version bump, tags the RC, creates a verification checklist in docs/releases/ , and pushes.

After /plot-release rc completes:

<promise>BLOCKED</promise>

The sprint is BLOCKED because the RC requires human testing. Do not output COMPLETE.

Promise Signals

Write a one-paragraph summary of what you accomplished this iteration, then output exactly one signal on its own line:

Signal When Loop effect

<promise>COMPLETE</promise>

All sprint tasks done, all PRs finalized, all demos created, RC tagged Loop exits, notifies human

<promise>BLOCKED</promise>

Truly stuck: unresolvable rebase conflict, RC tagged (awaiting human testing), needs human decision Loop exits, notifies human

(no signal) Did useful work, more to do Loop continues to next iteration

Do NOT output BLOCKED just because you posted review comments — fixing those is the next iteration's job.

Output COMPLETE only when the project's DoD is fully satisfied:

• If docs/definition-of-done.md exists: check every criterion in it

• If no DoD file: all PRs finalized per the AUTOMERGE setting, all CI green

Common Mistakes

Mistake Effect Prevention

Running against a sprint in Phase: Draft

No items to work on; loop exhausts iterations Check Phase: field in Step 0; output BLOCKED if not started

Outputting BLOCKED after posting review comments Loop exits; human must restart BLOCKED only when truly stuck — review comments are normal iteration work

Building a new task when unreviewed PRs exist Step 4 is skipped; review debt accumulates Step ordering is strict: fix → finalize → build → review

Creating feature/ branch for plan-only work Wasted PR, confuses sprint state Plan-only items commit directly to main

Working in a stale worktree New sprint items/merged PRs invisible to agent ralph-sprint.sh now refreshes worktrees before the loop; if running manually, git worktree remove first

Declaring BLOCKED with existing RC when new commits exist RC is stale, needs re-tagging Step 0 checks for commits after latest RC tag