From 1d9fd0aee98541752ef22fb27ffa73a48e6a34c1 Mon Sep 17 00:00:00 2001 From: John Ogle Date: Wed, 14 Jan 2026 13:53:42 -0800 Subject: [PATCH] feat(skills): Add batch research+plan skill for multiple beads --- .../skills/beads_batch_research_plan.md | 317 ++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 home/roles/development/skills/beads_batch_research_plan.md diff --git a/home/roles/development/skills/beads_batch_research_plan.md b/home/roles/development/skills/beads_batch_research_plan.md new file mode 100644 index 0000000..0c21d47 --- /dev/null +++ b/home/roles/development/skills/beads_batch_research_plan.md @@ -0,0 +1,317 @@ +--- +description: Batch research and planning for multiple beads with interactive question review +model: opus +--- + +# Beads Batch Research+Plan + +This skill automates the common workflow of: +1. Running /beads_research in parallel for multiple beads +2. Presenting open questions interactively for user input (bead-by-bead) +3. Running /beads_plan for all researched beads (plus any spawned from splits) + +## When to Use + +- You have multiple beads ready for work +- You want to research and plan them efficiently before implementation +- You prefer to batch your question-answering rather than context-switching between skills + +## Phase 1: Selection + +1. **Get ready beads**: Run `bd ready --limit=20` to list beads with no blockers + +2. **Filter already-researched beads**: + For each ready bead, check if it already has research: + ```bash + ls thoughts/beads-{bead-id}/research.md 2>/dev/null + ``` + + Categorize beads: + - **Needs research**: No `research.md` exists + - **Has research, needs plan**: `research.md` exists but no `plan.md` + - **Already planned**: Both `research.md` and `plan.md` exist + +3. **Present selection**: + ``` + Ready beads available for batch research+plan: + + NEEDS RESEARCH: + - {bead-id}: {title} (type: {type}) + - ... + + HAS RESEARCH (plan only): + - {bead-id}: {title} (type: {type}) + - ... + + ALREADY PLANNED (skip): + - {bead-id}: {title} + + Which beads would you like to process? + ``` + +4. **Use AskUserQuestion** with `multiSelect: true`: + - Include bead ID and title for each option + - Separate options by category + - Allow selection across categories + +## Phase 2: Parallel Research + +For each selected bead that NEEDS RESEARCH, launch a research subagent. + +### Subagent Instructions Template + +``` +Research bead [BEAD_ID]: [BEAD_TITLE] + +1. **Load bead context**: + ```bash + bd show [BEAD_ID] + ``` + +2. **Create artifact directory**: + ```bash + mkdir -p thoughts/beads-[BEAD_ID] + ``` + +3. **Conduct research** following beads_research.md patterns: + - Analyze and decompose the research question + - Spawn parallel sub-agent tasks (codebase-locator, codebase-analyzer, etc.) + - Synthesize findings + +4. **Write research document** to `thoughts/beads-[BEAD_ID]/research.md`: + - Include frontmatter with metadata + - Document findings with file:line references + - **CRITICAL**: Include "## Open Questions" section listing any unresolved items + +5. **Return summary**: + - Research status (complete/partial) + - Number of open questions + - Key findings summary (2-3 bullet points) + - List of open questions verbatim +``` + +### Launching Subagents + +Use `subagent_type: "opus"` for research subagents (matches beads_research model setting). + +Launch ALL research subagents in a single message for parallel execution: +``` + +``` + +### Collecting Results + +Wait for ALL research subagents to complete. Collect: +- Bead ID +- Research status +- Open questions list +- Any errors encountered + +## Phase 3: Interactive Question Review + +Present each bead's open questions sequentially for user input. + +### For Each Bead (in order): + +1. **Present research summary**: + ``` + ## Bead {N}/{total}: {bead-id} - {title} + + Research complete. Key findings: + - {finding 1} + - {finding 2} + + Open questions requiring your input: + 1. {question 1} + 2. {question 2} + + Additionally: + - Should this bead be split into multiple beads? (y/n) + - If split, describe the split: + ``` + +2. **Collect user responses**: + - Answers to open questions + - Split decision (yes/no) + - If split: new bead titles and how to divide the work + +3. **Handle splits**: + If user indicates a split: + ```bash + # Create new beads for split work + bd create --title="{split title 1}" --type={type} --priority={priority} \ + --description="{description based on user input}" + + # Update original bead if scope narrowed + bd update {original-bead-id} --description="{updated description}" + ``` + + Track new bead IDs for inclusion in planning phase. + +4. **Update research document**: + Append user answers to `thoughts/beads-{id}/research.md`: + ```markdown + ## User Clarifications [{timestamp}] + + Q: {question 1} + A: {user answer 1} + + Q: {question 2} + A: {user answer 2} + + ## Bead Splits + {If split: description of split and new bead IDs} + ``` + +### Progress Tracking + +After each bead's questions are answered, confirm before moving to next: +``` +Questions answered for {bead-id}. {N-1} beads remaining. +Continue to next bead? (y/n) +``` + +### Beads with No Questions + +If a bead's research had no open questions: +``` +## Bead {N}/{total}: {bead-id} - {title} + +Research complete with no open questions. + +Key findings: +- {finding 1} +- {finding 2} + +Should this bead be split? (y/n) +``` + +## Phase 4: Parallel Planning + +After all questions answered, launch planning subagents for all beads. + +### Beads to Plan + +Include: +- Original beads that were researched +- Beads that had existing research (from selection phase) +- New beads spawned from splits + +### Subagent Instructions Template + +``` +Create implementation plan for bead [BEAD_ID]: [BEAD_TITLE] + +1. **Load context**: + ```bash + bd show [BEAD_ID] + ``` + +2. **Read research** (it exists and has user clarifications): + Read `thoughts/beads-[BEAD_ID]/research.md` FULLY + +3. **Create plan** following beads_plan.md patterns: + - Context gathering via sub-agents + - Design approach based on research findings and user clarifications + - **Skip interactive questions** - they were already answered in research review + +4. **Write plan** to `thoughts/beads-[BEAD_ID]/plan.md`: + - Full plan structure with phases + - Success criteria (automated and manual) + - References to research document + +5. **Update bead**: + ```bash + bd update [BEAD_ID] --notes="Plan created: thoughts/beads-[BEAD_ID]/plan.md" + ``` + +6. **Return summary**: + - Plan status (complete/failed) + - Number of phases + - Estimated complexity (small/medium/large) + - Any issues encountered +``` + +### Launching Subagents + +Use `subagent_type: "opus"` for planning subagents (matches beads_plan model setting). + +Launch ALL planning subagents in a single message: +``` + +``` + +### Handling Beads Without Research + +For beads that had existing research but user didn't review questions: +- Planning subagent reads existing research +- If research has unresolved open questions, subagent should flag this in its return + +## Phase 5: Summary + +After all planning completes, present final summary. + +### Summary Format + +``` +## Batch Research+Plan Complete + +### Successfully Processed: +| Bead | Title | Research | Plan | Phases | Complexity | +|------|-------|----------|------|--------|------------| +| {id} | {title} | Complete | Complete | 3 | medium | +| {id} | {title} | Complete | Complete | 2 | small | + +### New Beads (from splits): +| Bead | Title | Parent | Status | +|------|-------|--------|--------| +| {new-id} | {title} | {parent-id} | Planned | + +### Failed: +| Bead | Title | Phase Failed | Error | +|------|-------|--------------|-------| +| {id} | {title} | Research | Timeout | + +### Next Steps: +1. Review plans at `thoughts/beads-{id}/plan.md` +2. Run `/parallel_beads` to implement all planned beads +3. Or run `/beads_implement {id}` for individual implementation + +### Artifacts Created: +- Research: thoughts/beads-{id}/research.md (x{N} files) +- Plans: thoughts/beads-{id}/plan.md (x{N} files) +``` + +## Error Handling + +### Research Subagent Failure +- Log the failure with bead ID and error +- Continue with other beads +- Exclude failed beads from question review and planning +- Report in final summary + +### Planning Subagent Failure +- Log the failure with bead ID and error +- Research still valid - can retry planning manually +- Report in final summary + +### User Cancellation During Question Review +- Save progress to bead notes +- Report which beads were completed +- User can resume with remaining beads in new session + +### Split Bead Creation Failure +- Report error but continue with original bead +- User can manually create split beads later + +## Resource Limits + +- Maximum concurrent research subagents: 5 +- Maximum concurrent planning subagents: 5 +- If more beads selected, process in batches + +## Notes + +- This skill is designed for the "research+plan before implementation" workflow +- Pairs well with `/parallel_beads` for subsequent implementation +- Run `/reconcile_beads` after implementation PRs merge