From 6441352ed9cc66eda8ffc801ace2d01fa4087a19 Mon Sep 17 00:00:00 2001
From: John Ogle <john@ogle.fyi>
Date: Sat, 10 Jan 2026 12:38:06 -0800
Subject: [PATCH] feat(skills): Improve parallel beads workflow with in_review
 status

- Add step to mark beads as 'in_review' after PR creation
- Add PR URL to bead notes for traceability
- Create reconcile_beads skill to close beads when PRs are merged
- Update summary table to show bead status instead of generic status

Implements bead: nixos-configs-85h
---
 .../development/skills/parallel_beads.md      | 19 +++--
 .../development/skills/reconcile_beads.md     | 85 +++++++++++++++++++
 2 files changed, 98 insertions(+), 6 deletions(-)
 create mode 100644 home/roles/development/skills/reconcile_beads.md

diff --git a/home/roles/development/skills/parallel_beads.md b/home/roles/development/skills/parallel_beads.md
index 4eb38aa..e4d36a4 100644
--- a/home/roles/development/skills/parallel_beads.md
+++ b/home/roles/development/skills/parallel_beads.md
@@ -93,7 +93,13 @@ Work on bead [BEAD_ID]: [BEAD_TITLE]
      - [List of changes made]"
      ```
 
-6. **Report results**:
+6. **Update bead status**:
+   - Mark the bead as "in_review": `bd update [BEAD_ID] --status=in_review`
+   - Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes')
+
+PR: [PR_URL]"`
+
+7. **Report results**:
    - Return: PR URL, bead ID, success/failure status
    - If blocked or unable to complete, explain what's blocking progress
 ```
@@ -165,11 +171,11 @@ Example output:
 ```
 ## Parallel Beads Summary
 
-| Bead | PR | Status | Review |
-|------|-----|--------|--------|
-| beads-abc | #123 | Success | Approved |
-| beads-xyz | #124 | Success | Needs changes |
-| beads-123 | - | Failed | Blocked by missing dependency |
+| Bead | PR | Bead Status | Review |
+|------|-----|-------------|--------|
+| beads-abc | #123 | in_review | Approved |
+| beads-xyz | #124 | in_review | Needs changes |
+| beads-123 | - | open (failed) | Blocked by missing dependency |
 
 ### Failures/Blockers
 - beads-123: Could not complete because [reason]
@@ -177,6 +183,7 @@ Example output:
 ### Next Steps
 - Review PRs that need changes
 - Address blockers for failed beads
+- Run `/reconcile_beads` after PRs are merged to close beads
 ```
 
 ## Error Handling
diff --git a/home/roles/development/skills/reconcile_beads.md b/home/roles/development/skills/reconcile_beads.md
new file mode 100644
index 0000000..3b36778
--- /dev/null
+++ b/home/roles/development/skills/reconcile_beads.md
@@ -0,0 +1,85 @@
+---
+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.
+
+## 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
+
+## Workflow
+
+### Step 1: Find beads in review
+
+```bash
+bd list --status=in_review
+```
+
+### Step 2: For each bead, check PR status
+
+1. **Get the PR URL from bead notes**:
+   ```bash
+   bd show [BEAD_ID] --json | jq -r '.notes'
+   ```
+   Extract the PR URL (look for lines starting with "PR:" or containing pull request URLs)
+
+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:
+     ```bash
+     gh pr view [PR_NUMBER] --json state,merged
+     ```
+   - For Gitea:
+     ```bash
+     tea pr view [PR_NUMBER]
+     ```
+     Look for "State: merged" or "State: closed"
+
+### Step 3: Close merged beads
+
+If the PR is merged:
+```bash
+bd close [BEAD_ID] --reason="PR merged: [PR_URL]"
+```
+
+### Step 4: Report summary
+
+Present results:
+
+```
+## Beads Reconciliation Summary
+
+### Closed (PR Merged)
+| Bead | PR | Title |
+|------|-----|-------|
+| beads-abc | #123 | Feature X |
+| beads-xyz | #456 | Bug fix Y |
+
+### 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
+
+## 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
-- 
2.49.1