nixos-configs/home/roles/development/skills/reconcile_beads.md

description

description
Reconcile beads with merged PRs and close completed beads

Reconcile Beads Workflow

This skill reconciles beads that are in in_review status with their corresponding PRs. If a PR has been merged, the bead is closed and any linked Gitea issue is also closed.

Prerequisites

• Custom status in_review must be configured: bd config set status.custom "in_review"
• Beads in in_review status should have a PR URL in their notes
• tea CLI must be configured for closing Gitea issues

Workflow

Step 1: Find beads in review

bd list --status=in_review

Step 2: For each bead, check PR status

1. Get the PR URL from bead notes:

   bd show [BEAD_ID] --json | jq -r '.[0].notes'
   

   Note: bd show --json returns an array, so use .[0] to access the first element. Extract the PR URL (look for lines starting with "PR:" or containing pull request URLs). Extract the PR number: echo "$NOTES" | grep -oP '/pulls/\K\d+'

2. Detect hosting provider:

   • Run git remote get-url origin
   • If URL contains github.com, use gh; otherwise use tea (Gitea/Forgejo)

3. Check PR status:

   • For GitHub:

     gh pr view [PR_NUMBER] --json state,merged
     

   • For Gitea:

     tea pr list --state=closed
     

     Look for the PR number in the INDEX column with STATE "merged". Note: tea pr view [PR_NUMBER] lists all PRs, not a specific one. Use tea pr list --state=closed and look for your PR number in the results.

Step 3: Close merged beads

If the PR is merged:

bd close [BEAD_ID] --reason="PR merged: [PR_URL]"

Step 3.1: Close corresponding Gitea issue (if any)

After closing a bead, check if it has a linked Gitea issue:

1. Check for Gitea issue URL in bead notes: Look for the pattern Gitea issue: <URL> in the notes. Extract the URL.

2. Extract issue number from URL:

   # Example: https://git.johnogle.info/johno/nixos-configs/issues/16 -> 16
   echo "$GITEA_URL" | grep -oP '/issues/\K\d+'
   

3. Close the Gitea issue:

   tea issues close [ISSUE_NUMBER]
   

4. Handle errors gracefully:

   • If issue is already closed: Log warning, continue
   • If issue not found: Log warning, continue
   • If tea fails: Log error, continue with other beads

   Example warning output:

   Warning: Could not close Gitea issue #16: issue already closed
   

Step 4: Report summary

Present results:

## Beads Reconciliation Summary

### Closed (PR Merged)
| Bead | PR | Gitea Issue | Title |
|------|-----|-------------|-------|
| beads-abc | #123 | #16 closed | Feature X |
| beads-xyz | #456 | (none) | Bug fix Y |

### Gitea Issues Closed
| Issue | Bead | Status |
|-------|------|--------|
| #16 | beads-abc | Closed successfully |
| #17 | beads-def | Already closed (skipped) |
| #99 | beads-ghi | Error: issue not found |

### Still in Review
| Bead | PR | Status | Title |
|------|-----|--------|-------|
| beads-def | #789 | Open | Feature Z |

### Issues Found
- beads-ghi: No PR URL found in notes
- beads-jkl: PR #999 not found (may have been deleted)

Error Handling

• Missing PR URL: Skip the bead and report it
• PR not found: Report the error but continue with other beads
• API errors: Report and continue
• Gitea issue already closed: Log warning, continue (not an error)
• Gitea issue not found: Log warning, continue (issue may have been deleted)
• No Gitea issue linked: Normal case, no action needed
• tea command fails: Log error with output, continue with other beads

Notes

• This skill complements /parallel_beads which sets beads to in_review status
• Run this skill periodically or after merging PRs to keep beads in sync
• Beads with closed (but not merged) PRs are not automatically closed - they may need rework
• Gitea issues are only closed for beads that have a Gitea issue: <URL> in their notes