rc-next

Read the bead graph and advance the QRDS-PI cycle.

Epic input: $ARGUMENTS

What this skill does

This is the daily driver. Every invocation:

1. Reads the bead graph fresh (no accumulated context)
2. Determines where the cycle is
3. Reports state to the human
4. When structure is complete: presents the plan for review
5. When cycle is complete: offers to iterate with feedback

Prerequisites

• bd CLI installed (bd --version >= 1.0.0)
• .beads/ workspace initialized in the current project

Steps

1. Find the epic

If $ARGUMENTS contains an epic ID, use that.

If no argument provided, find all epics (including closed ones):

bd list --type epic --json

Include closed epics — the user may want to iterate on a completed cycle. Sort by most recently updated.

If exactly one epic, use it automatically.

If multiple epics, present the list and ask which one:

"Found these epics:"

• <id>: — <status> "Which one?"

If none found:

"No epics found. Start with: rc-questions <task description>"

2. Read the bead graph

bd children <epic-id> --json
bd gate list --json
bd ready --json

Parse phase beads. Check for child beads under research (mitosis):

bd children <research-bead-id> --json 2>/dev/null

3. Determine current state and act

Walk the phase chain and handle the appropriate case:

---

Case: questions bead is open

"Epic <id>: Questions phase." "Run rc-questions to start the interview."

---

Case: questions closed, R-D-S in progress or ready

Show progress:

"Epic <id>: Autonomous QRDS in progress."

• Research: [status] [child bead count if any]
• Design: [status]
• Design-review: [status]
• Structured-outline: [status]

[if research is ready and loop hasn't started]: "Start the loop: ralph-loop <epic-id> --worktree"

---

Case: all phase beads closed (cycle complete)

This is the main interaction point. The QRDS cycle finished. Read the structure document and present it for review.

bd show <structure-bead-id>
bd show <design-bead-id>
bd show <design-review-bead-id>

Present the full structure outline:

"Epic <id>: QRDS cycle complete. Structure ready for review."

Design approach:

Review findings: <extract issues/verdict from design-review bead>

Structure outline:

"If you approve, PI starts next. plan-research will write a checked-in ExecPlan under plans/, then expand will slice implementation beads from that plan."

Then present options using AskUserQuestion:

Question: "QRDS cycle complete. Structure is ready for review. What would you like to do?" Header: "Plan review" Options:

1. Approve (Recommended) — "Proceed to PI: write the ExecPlan, review it, then expand into implementation beads."
2. Iterate — "Provide feedback and run another R-D-S pass."
3. View details — "Read a specific bead in full before deciding."

---

Case: human says "approve"

The structured outline is accepted. The PI (Plan + Implement) pipeline beads already exist (stamped by the formula). Close the gate to unblock them.

1. Close the QRDS gate to unblock plan-research:

Find the open gate:human bead (not gate:human-merge) under this epic:

bd children <epic-id> --json

Find the bead whose title starts with gate:human (not gate:human-merge) and status is open. Close it:

bd close <gate-bead-id>

This unblocks the plan-research bead, which was already stamped by the formula.

2. Report:

"Plan approved. PI pipeline is unblocked:" "plan-research → plan-review → expand → expand-review → convention-audit → adversarial-review → epilogue → gate:human-merge"

"Run: ralph-loop <epic-id>" "Expected artifact flow: plan-research writes plans/<epic-slug>.md, plan-review audits that ExecPlan, then expand stamps implementation beads from it."

"When the loop finishes, run rc-next to review the diff, the ExecPlan-backed implementation, and merge."

---

Case: human says "iterate" or provides feedback

This is the iteration flow. The human has feedback on the structure document. Start a new QRDS pass that builds on the existing one.

1. Reopen the epic:

bd reopen <epic-id>

2. Collect feedback — ask the human what needs to change. This is a focused interview, not a full re-do. Batch the questions:

"What needs to change? I'll read the existing plan and your feedback, then run another R-D-S pass. Tell me everything — what's wrong, what's missing, what should be different."

3. Create new iteration beads under the same epic. Number them to distinguish from the first pass:

bd create --parent <epic-id> --title "questions-v2: <name>" \
  --description "<feedback + reference to existing structure bead>" \
  --type task

bd create --parent <epic-id> --title "research-v2: <name>" \
  --deps "<questions-v2-id>" \
  --description "<enriched research instructions referencing both the v1 structure and the feedback>" \
  --type task

bd create --parent <epic-id> --title "design-v2: <name>" \
  --deps "<research-v2-id>" \
  --description "<enriched design instructions>" \
  --type task

bd create --parent <epic-id> --title "design-review-v2: <name>" \
  --deps "<design-v2-id>" \
  --description "<enriched review instructions>" \
  --type task

bd create --parent <epic-id> --title "structured-outline-v2: <name>" \
  --deps "<design-review-v2-id>" \
  --description "<enriched structured-outline instructions — must produce UPDATED outline incorporating feedback>" \
  --type task

Use plain bead IDs in --deps. blocks:X means X blocks me, which reverses the intended chain in these examples.

4. Enrich the new bead descriptions with concrete IDs — the v2 research bead should read BOTH the v1 structure bead AND the v2 questions (feedback) bead. The v2 design bead reads v2 research. And so on.

5. Write feedback into the v2 questions bead and close it:

bd update <questions-v2-id> --description "<human's feedback + what to change>"
bd close <questions-v2-id>

6. Report the command to run the next pass:

"Iteration beads stamped. The v2 pass will build on the existing plan with your feedback." "Run: ralph-loop <epic-id> --worktree"

The ralph-loop will pick up the v2 beads (the v1 beads are already closed, so they won't be picked again). The v2 structured-outline bead produces an UPDATED outline.

---

Case: expand bead exists (implementation pipeline stamped)

The expand bead or implementation beads are in progress.

Read the plan bead too so you can surface the current ExecPlan path when present:

bd show <plan-research-bead-id>

bd children <epic-id> --json

Look for beads with titles starting with "expand:", "implement:", or "epilogue:".

"Epic <id>: Implementation in progress." "Current implementation contract: <ExecPlan path from the plan-research bead, if present; otherwise say the plan is still bead-only until plan-research writes it.>"

Show implementation bead status:

Bead	Status
expand: create implementation beads	[closed/in_progress]
implement:	[closed/open/in_progress]
implement:	[closed/open/in_progress]
...
epilogue: review and verify	[blocked/open]

Progress: X/Y implementation beads complete. [if loop is not running]: "Continue: ralph-loop <epic-id> --worktree"

---

Case: epilogue bead is closed

Check if the epilogue found issues (discovery beads).

bd children <epic-id> --json

Look for beads with type "bug" or titles starting with "fix:" — these are discoveries from the epilogue.

Check for worktree branch:

git rev-parse --verify ralph-loop/<epic-id> 2>/dev/null

If the branch exists, present a structured review before the AskUserQuestion:

1. Diff summary (what changed):

git diff --stat main...ralph-loop/<epic-id>

Output as:

Changes on branch ralph-loop/<epic-id>:

<git diff --stat output>

2. Key changes (actual code, not just file names):

Run:

git diff main...ralph-loop/<epic-id>

Pick the 3–5 most significant hunks — prefer new functions, changed logic, or deleted code over whitespace and import changes. Excerpt them inline:

Key changes:

path/to/file.ext —

<hunk excerpt>

(repeat for each key change)

3. Epilogue verification findings:

bd show <epilogue-bead-id>

Extract the verdict and any issues found:

Epilogue verdict: <pass / issues found>

4. Structure outline (reference):

bd show <structure-bead-id>

Show the outline title and first few lines only — this is a reference anchor, not the focus:

Plan reference (<structure-bead-id>): (Full outline available via bd show <structure-bead-id>)

Then present options using AskUserQuestion:

If discoveries exist:

Question: "Implementation complete. Epilogue found N issues. How do you want to proceed?" Header: "Next step" Options:

1. Merge to main — "Merge the worktree branch and create PR. Discoveries become follow-up work."
2. Fix discoveries — "Run ralph-loop to execute fix beads before merging."
3. View full diff — "Show the complete diff for review before deciding."
4. New QRDS cycle — "Deep planning for a complex discovery."

If no discoveries:

Question: "Implementation complete. Clean epilogue. How do you want to proceed?" Header: "Next step" Options:

1. Merge to main (Recommended) — "Merge the worktree branch to main and create PR."
2. View full diff — "Show the complete diff before merging."
3. Iterate — "Provide feedback and run another pass."

If NO worktree branch exists (legacy runs without --worktree):

Present options using AskUserQuestion:

Question: "Implementation complete. Clean epilogue. Ready to create PR?" Header: "Next step" Options:

1. Create PR (Recommended) — "Create a pull request with the implementation."
2. Iterate — "Provide feedback and run another pass."

---

Case: human says "create PR"

Create a PR from the current branch with a summary drawn from the epic's beads.

1. Read the structure bead for the plan summary
2. Read the epilogue bead for review findings
3. Create the PR:

git add -A
git commit -m "[ralph-crispies] <epic-title>"
gh pr create --title "<epic-title>" --body "$(cat <<'PR_EOF'
## Summary

<summarize from structure bead — what was built and why>

## Implementation

<list of files created/modified from implementation beads>

## Review Notes

<epilogue findings, if any>

## Test Plan

<acceptance criteria from structure bead>

Generated by Ralph Crispies QRDS-PI cycle.
Epic: <epic-id>
PR_EOF
)"

"PR created: " "If review feedback comes back, run rc-next <epic-id> and choose iterate with the feedback."

---

Case: human says "merge to main"

Merge the worktree branch and create a PR.

1. Merge the branch:

git merge ralph-loop/<epic-id>

2. Then follow the existing "create PR" case flow.

---

Case: human says "view full diff"

Show the full diff:

git diff main...ralph-loop/<epic-id>

Then re-present the same AskUserQuestion options (minus "View full diff").

---

Case: human provides PR review feedback

Same as the "iterate" case — but the feedback source is PR review comments rather than structure doc review. The v2 questions bead should reference the PR URL and specific review comments.

---

4. Show the full graph

Always end with the current bead graph:

bd list --parent <epic-id>

Hard rules

1. Every invocation reads the bead graph fresh. No accumulated context.
2. When presenting the structure document for review, show the FULL outline. Don't summarize the plan — that's what the human reviews.
3. Present research and design as context/summary only.
4. The iteration flow creates NEW beads (v2, v3, etc.) under the same epic. It does NOT modify closed beads from previous passes.
5. v2 research reads BOTH the v1 structure AND v2 feedback — it needs to understand what exists and what's changing.
6. Enrich all new bead descriptions with concrete bead IDs.
7. Report child beads (mitosis) when showing phase status.
8. Never tell the user to run bd close or bd gate resolve manually.