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

description, model

description	model
Batch research and planning for multiple beads with interactive question review	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:

   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:

   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:

   ## 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:

   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