bead-polishing-ralph

Bead Polishing for Ralph-TUI

Iteratively refine beads through 4-6 polishing rounds until convergence, enforcing all constraints that ralph-tui needs for successful autonomous execution.

This skill combines the convergence-tracked polishing loop from the Agentic Coding Flywheel with the specific format and sizing constraints required by ralph-tui's beads tracker.

Why This Matters

ralph-tui spawns a fresh agent instance per bead with no memory of previous work. A bead that is too big, vague, or has broken dependencies will cause the agent to either run out of context, produce the wrong thing, or block the entire pipeline. Polishing beads before execution is the single highest-ROI activity because:

• Plan mistakes cost 1x to fix (edit the markdown)
• Bead mistakes cost 5x to fix (rewrite + re-link + re-order)
• Code mistakes cost 25x to fix (debug + refactor + retest across files)

A 30-second fix to a bead description prevents a 30-minute failed ralph-tui iteration.

---

Before Starting

Detect CLI

Use bd (beads) as the CLI for all bead operations. The polishing process uses bd commands throughout.

Gather Context

1. Read the source plan/PRD that the beads were created from. Polishing without the source is guessing.
2. Extract Quality Gates from the PRD's "Quality Gates" section. If none exists, ask the user what commands should pass (e.g., pnpm typecheck, pnpm lint).
3. Check if beads exist: bd list --json

Create Beads if None Exist

If no beads exist yet, create them from the source PRD before polishing. This makes the separate "convert to tasks" step optional — bead-polishing-ralph can handle the full plan-to-polished-beads pipeline.

1. Create an epic linking back to the PRD:

   bd create --type=epic \
     --title="[Feature Name]" \
     --description="$(cat <<'EOF'
   [Feature description from PRD]
   EOF
   )" \
     --external-ref="prd:./path-to-prd.md"
   

2. Create one bead per user story/requirement from the PRD. For each story:

   • Title matches the story title
   • Description includes story context, acceptance criteria, quality gates, and the <promise>COMPLETE</promise> instruction
   • Priority reflects dependency order (schema=1, backend=2, UI=3, polish=4)
   • Pass --parent=<epic-id> at creation time so the parent link exists from the start