dotfiles/dot_claude/commands/bd-drain.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Recursively implement all pending beads issues until every one is closed with tests passing, builds succeeding, requirements met, and blockers cleared	optional priority filter e.g. "p0-p2" | epic id | "dry-run"	Bash(bd:*), Bash(git:*), Bash(go:*), Bash(pnpm:*), Bash(cargo:*), Bash(make:*), Read, Write, Edit, Glob, Grep, Task

/bd-drain — Recursive Beads Completion Workflow

Drain the beads backlog to zero. Work every ready issue to full completion, unblock dependent issues as they clear, and repeat until no open, actionable work remains. Arguments: $ARGUMENTS (optional priority filter like p0-p2, an epic ID to scope to, or dry-run to plan without executing).

Phase 0 — Session Bootstrap

1. Run bd dolt pull to sync beads state from remote.
2. Run bd prime if context was compacted or this is a fresh session.
3. Run bd doctor — if sync problems or missing hooks are reported, fix them before proceeding.
4. Run bd stats and record the baseline: open / in_progress / blocked counts. This is the burn-down target.
5. Run bd memories drain and bd memories <project keyword> to load any prior insights about this workflow or codebase gotchas.
6. Detect the project's verification commands by inspecting the repo (Makefile, Taskfile, turbo.json, package.json scripts, go.mod, Cargo.toml). Record:
   • TEST_CMD (e.g. go test ./..., pnpm turbo test, cargo test)
   • BUILD_CMD (e.g. go build ./..., pnpm turbo build)
   • LINT_CMD if present (e.g. golangci-lint run, pnpm lint)
7. Run TEST_CMD and BUILD_CMD once before touching anything to establish a green baseline. If the baseline is already red, create a P0 bug with bd create describing the pre-existing failure and fix it first — never build on a broken base.

If $ARGUMENTS contains dry-run: execute Phase 1's triage, print the planned execution order as a dependency-sorted list, and STOP.

Phase 1 — Triage & Ordering

1. Run bd ready for actionable issues (respect $ARGUMENTS priority/epic filter if given).
2. Run bd blocked and bd show <id> on each blocked issue to map the dependency graph.
3. Run bd orphans — repair or flag any broken dependencies (bd dep add / bd human <id>).
4. Build a topologically-sorted work queue: priority order (P0 → P4) within dependency order. Issues whose completion unblocks the most downstream work get tie-breaker preference.
5. Run bd lint on the queue. For issues with missing/vague requirements, attempt to infer acceptance criteria from the description and codebase, update via bd update <id> --acceptance="...". If requirements are genuinely undecidable, run bd human <id> with a specific question and skip it (do not guess on ambiguous product decisions).

Phase 2 — The Drain Loop

Repeat until the exit condition in Phase 3 is met. For each issue in the queue:

2a. Claim

bd show <id>            # re-read full details, dependencies, acceptance criteria
bd update <id> --claim  # mark in_progress

2b. Implement

• Read the acceptance criteria, design notes, and any linked issues before writing code.
• Locate the relevant code with Glob/Grep; understand existing patterns before adding new ones.
• Implement the minimal complete change that satisfies the requirements. Follow existing repo conventions.
• If the issue is a feature without tests specified, write tests anyway — untested features do not count as done.
• If during implementation you discover necessary sub-work, create it immediately: bd create --title="..." --description="..." --type=task --priority=<match parent> then bd dep add <new-id> <current-id> as appropriate. Never leave discovered work untracked.

2c. Verify (hard gates — ALL must pass)

<TEST_CMD>    # full test suite, not just new tests
<BUILD_CMD>   # full build
<LINT_CMD>    # if present

• ✅ All tests pass (including pre-existing ones — no regressions)
• ✅ Build succeeds cleanly
• ✅ Every acceptance criterion on the issue is demonstrably met
• ✅ No new warnings/lint errors introduced

On failure: fix and re-verify. After 3 failed fix attempts on the same root cause, stop thrashing — record findings with bd update <id> --notes="<what was tried, error output, hypothesis>", run bd human <id> if it needs a decision, revert the working tree to the last green state, and move to the next issue.

2d. Close & Checkpoint

bd close <id> --reason="<one-line summary of what was done>" --suggest-next
bd remember "<any non-obvious insight learned: gotcha, pattern, decision>"
git add <changed files>
git commit -m "<type>(<scope>): <summary> (closes <id>)"

• Commit per issue, not in batches — each commit should be independently green.
• --suggest-next output feeds Phase 2e.

2e. Re-plan

• Newly unblocked issues from --suggest-next are inserted into the queue in priority order.
• Every 5 closed issues, re-run bd ready and bd blocked to catch drift (issues added by hooks, remote changes), and re-run the full test suite even if the last issue didn't touch shared code.

Parallelism

When the queue contains independent issues (no shared files, no dependency relation), dispatch up to 3 in parallel via the Task tool (subagents), each following 2a–2d in isolation. Serialize anything touching shared modules, migrations, or config. Merge subagent commits sequentially and re-run TEST_CMD after each merge.

Phase 3 — Exit Conditions & Escalation

The loop terminates when one of these holds:

1. Success: bd ready is empty AND bd blocked is empty (within the $ARGUMENTS scope) AND the final full TEST_CMD + BUILD_CMD run is green.
2. Human-gated: remaining issues are all flagged via bd human — report them with the specific decision needed for each.
3. Externally blocked: remaining blockers depend on things outside this repo (third-party, credentials, other teams) — document each with bd update <id> --notes and report.

Never terminate by silently skipping issues. Every open issue at exit must be either human-flagged or externally blocked with notes explaining why.

Phase 4 — Session Close Protocol (MANDATORY)

[ ] git status              # confirm nothing unstaged/untracked left behind
[ ] git add <files>         # stage any stragglers
[ ] bd dolt pull            # pull beads updates from main
[ ] git commit -m "..."     # final commit if anything staged
[ ] bd stats                # final counts

Then produce the Drain Report:

• Burn-down: baseline vs final counts (open / in_progress / blocked / closed this session)
• Closed: each issue ID + one-line summary + commit SHA
• Escalated: each bd human flag with the exact decision needed
• Externally blocked: each with the external dependency named
• Discovered work: new issues created during the drain
• Insights recorded: bd remember entries added
• Final verification: test suite result, build result, lint result

Hard Rules

• Use beads for ALL tracking. Never TodoWrite, TaskCreate, or markdown task files.
• Never bd edit (blocks on $EDITOR).
• Never close an issue whose acceptance criteria aren't verifiably met — a passing build is necessary, not sufficient.
• Never commit with a red test suite.
• Priority values are numeric (0–4 / P0–P4), never "high"/"medium"/"low".
• Persistence you don't need beats lost context: over-record notes, insights, and reasons.