---
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:
```
<Task calls for each selected bead needing research - all in one message>
```

### 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:
```
<Task calls for each bead to plan - all in one 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