dotfiles/dot_claude/commands/bd-drain.md

---
description: Recursively implement all pending beads issues until every one is closed with tests passing, builds succeeding, requirements met, and blockers cleared
argument-hint: [optional: priority filter e.g. "p0-p2" | epic id | "dry-run"]
allowed-tools: 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
```bash
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)
```bash
<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
```bash
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)

```bash
[ ] 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.