Never Skip a Step Again: Crash-Proof PR Reviews with Beads

pr-review-workflow-article.md

Never Skip a Step Again: Crash-Proof PR Reviews with Beads

You're reviewing a PR. You've read the description, checked out the branch, started going through the code. Then Slack explodes. Or you get pulled into an incident. Or it's 6pm and you'll "finish tomorrow."

Tomorrow: where were you? Did you run the tests? Did you check for security issues?

Mental checklists don't survive interruptions. You forget. You skip steps. You approve a PR that breaks production because you didn't actually run the tests locally.

What if your review workflow could survive crashes, enforce thoroughness, and prove you did the work?

Enter Beads Formulas

Beads is a lightweight issue tracker with first-class dependency support. Formulas let you define multi-step workflows as templates that become real, trackable issues.

The key insight: your workflow becomes data, not just documentation.

Formula (template) → Proto (reusable) → Molecule (executable issues)

When you spawn a molecule from a formula:

• Each step becomes a real issue
• Dependencies are enforced - you can't approve before you've tested
• Progress survives crashes - just query "what's next?"
• Everything is auditable - who did what, when

A PR Review Formula

Let's build a thorough PR review workflow:

understand-context → checkout-branch → review-code ─┬─► check-tests
                                                    └─► check-security
                                                              ↓
                                    submit-review ← verify-ci ← (both complete)

You can't approve before running tests. You can't submit before checking security. Dependencies are enforced, not hoped for.

The Formula

Create .beads/formulas/pr-review.formula.toml:

description = """
Thorough PR review workflow.

Ensures every review covers:
- Understanding context (why this change?)
- Code quality (is it good?)
- Testing (does it work?)
- Security (is it safe?)

Variables:
  pr_number   - Pull request number
  repo        - Repository (owner/name)
  author      - PR author
  title       - PR title
"""

formula = "pr-review"
version = 1

[vars.pr_number]
description = "Pull request number"
required = true

[vars.repo]
description = "Repository (owner/name)"
required = true

[vars.author]
description = "PR author"
required = true

[vars.title]
description = "PR title"
required = true

[[steps]]
id = "understand-context"
title = "Understand the context"
description = """
Before looking at code, understand WHY this change exists.

PR: {{repo}}#{{pr_number}}
Author: {{author}}
Title: {{title}}

Checklist:
- Read PR description
- Check linked issues
- Understand the problem being solved
- Review any design docs or discussions

Exit criteria: You can explain the PR's purpose to someone else.
"""

[[steps]]
id = "checkout-branch"
title = "Checkout and build"
needs = ["understand-context"]
description = """
Get the code running locally.

Run: gh pr checkout {{pr_number}}

Checklist:
- Branch checked out
- Dependencies installed
- Project builds successfully

Exit criteria: Code compiles/builds locally.
"""

[[steps]]
id = "review-code"
title = "Review code changes"
needs = ["checkout-branch"]
description = """
Go through the diff carefully.

Run: gh pr diff {{pr_number}}

Code quality checklist:
- Logic is correct
- Code is readable
- No obvious bugs
- Error handling is appropriate
- No code duplication
- Follows project conventions

Leave inline comments as you go.

Exit criteria: All changed files reviewed, comments left.
"""

[[steps]]
id = "check-tests"
title = "Run tests locally"
needs = ["review-code"]
description = """
Don't trust CI alone. Run tests yourself.

Checklist:
- All tests pass
- Test coverage adequate for changes
- New functionality has tests
- Edge cases covered

Exit criteria: Tests pass locally.
"""

[[steps]]
id = "check-security"
title = "Security review"
needs = ["review-code"]
description = """
Check for security issues in the changes.

Checklist:
- No hardcoded secrets or credentials
- Input validation present
- No SQL injection vectors
- No XSS vulnerabilities
- Authentication/authorization correct
- Sensitive data handled properly

Exit criteria: No security concerns, or issues documented.
"""

[[steps]]
id = "verify-ci"
title = "Verify CI status"
needs = ["check-tests", "check-security"]
description = """
Confirm CI passes before approving.

Run: gh pr checks {{pr_number}}

Checklist:
- All CI checks pass
- No flaky test failures

Exit criteria: CI is green.
"""

[[steps]]
id = "submit-review"
title = "Submit review"
needs = ["verify-ci"]
description = """
Submit your review on GitHub.

To approve: gh pr review {{pr_number}} --approve
To request changes: gh pr review {{pr_number}} --request-changes

Checklist:
- Review submitted
- Summary comment explains decision
- Author notified

Exit criteria: Review submitted on GitHub.
"""

Using the Formula

1. See available formulas

bd formula list

Output:

pr-review    Thorough PR review workflow

2. Preview the workflow

bd cook pr-review --dry-run \
  --var pr_number=42 \
  --var repo=acme/webapp \
  --var author=alice \
  --var title="Add user authentication"

Shows what would be created without creating anything.

3. Spawn a molecule

bd mol spawn pr-review --pour \
  --var pr_number=42 \
  --var repo=acme/webapp \
  --var author=alice \
  --var title="Add user authentication"

Creates real issues:

bd-mol-abc     "pr-review: Add user authentication" (molecule)
├── bd-mol-abc.1  Understand the context
├── bd-mol-abc.2  Checkout and build
├── bd-mol-abc.3  Review code changes
├── bd-mol-abc.4  Run tests locally
├── bd-mol-abc.5  Security review
├── bd-mol-abc.6  Verify CI status
└── bd-mol-abc.7  Submit review

4. Work through it

See what's ready:

bd mol current bd-mol-abc

Output:

Ready:
  → bd-mol-abc.1  Understand the context

Blocked:
  bd-mol-abc.2  Checkout and build (needs: understand-context)
  ...

Complete steps as you go:

bd close bd-mol-abc.1   # Done reading context
bd close bd-mol-abc.2   # Branch checked out, builds
bd close bd-mol-abc.3   # Code reviewed

Now tests and security can run in parallel:

bd mol current bd-mol-abc

Output:

Ready:
  → bd-mol-abc.4  Run tests locally
  → bd-mol-abc.5  Security review

Blocked:
  bd-mol-abc.6  Verify CI status (needs: check-tests, check-security)

5. Crash recovery

Slack explodes. You context-switch. Next day:

bd mol current bd-mol-abc

Output:

Completed:
  ✓ bd-mol-abc.1  Understand the context
  ✓ bd-mol-abc.2  Checkout and build
  ✓ bd-mol-abc.3  Review code changes
  ✓ bd-mol-abc.4  Run tests locally

Ready:
  → bd-mol-abc.5  Security review

Blocked:
  bd-mol-abc.6  Verify CI status (needs: check-security)

The molecule IS the state. No memory required. No "where was I?"

6. Dependencies are enforced

Try to submit before security check:

bd close bd-mol-abc.7   # submit-review

Output:

Error: blocked by bd-mol-abc.5 (check-security)

You literally can't skip steps.

Why This Matters

Thoroughness by default

Every review follows the same process. No more "I just skimmed it."

Interruption-proof

Context-switch freely. The molecule remembers where you are.

Parallel where possible

Tests and security run in parallel - the formula encodes this.

Audit trail

Your tech lead asks: "Did you actually run the tests locally?"

bd show bd-mol-abc.4

Output:

ID: bd-mol-abc.4
Title: Run tests locally
Status: closed
Closed at: 2024-01-15 14:32:00
Closed by: bob

Proof, not promises.

Reusable across team

Same formula, everyone. Consistent reviews.

Quick Reference

# List formulas
bd formula list

# Preview what would be created
bd cook pr-review --dry-run --var pr_number=42 ...

# Create a molecule (persistent)
bd mol spawn pr-review --pour --var pr_number=42 ...

# What's ready?
bd mol current <mol-id>

# Complete a step
bd close <step-id>

# Show step details
bd show <step-id>

# When done, compress to digest
bd mol squash <mol-id>

Get Started

# Install beads
go install github.com/steveyegge/beads/cmd/bd@latest

# Initialize in your project
bd init

# Create formulas directory
mkdir -p .beads/formulas

# Create pr-review.formula.toml (copy from above)

# Start reviewing
bd mol spawn pr-review --pour \
  --var pr_number=123 \
  --var repo=myorg/myrepo \
  --var author=teammate \
  --var title="Feature X"

Conclusion

PR reviews fail because humans forget, rush, and lose context. Beads formulas turn your review process into executable, resumable, auditable data.

• Define once - formula captures your standards
• Enforce always - dependencies prevent skipping
• Recover anywhere - state survives interruptions
• Prove everything - audit trail is automatic

Stop hoping reviews are thorough. Encode thoroughness.

---

Beads is open source: github.com/steveyegge/beads