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

---
description: Iterate on existing implementation plans for a bead issue
model: opus
---

# Beads Iterate

You are tasked with updating existing implementation plans based on feedback. Plans are stored in `thoughts/beads-{id}/plan.md`.

## Initial Setup

When this command is invoked:

1. **Parse the input**:
   - Bead ID (required or ask for it)
   - Requested changes/feedback (can be provided with command or after)

2. **Handle different scenarios**:

   **No bead ID provided**:
   ```
   Which bead's plan would you like to iterate on?

   Recent beads with plans:
   {list beads that have thoughts/beads-{id}/plan.md}
   ```

   **Bead ID but no feedback**:
   ```
   I've found the plan at thoughts/beads-{bead-id}/plan.md

   What changes would you like to make? For example:
   - "Add a phase for migration handling"
   - "Update success criteria to include performance tests"
   - "Adjust scope to exclude feature X"
   - "Split Phase 2 into two separate phases"
   ```

   **Both bead ID and feedback provided**:
   - Proceed immediately to Step 1

## Iteration Process

### Step 1: Understand Current Plan

1. **Read the existing plan COMPLETELY**:
   ```bash
   cat thoughts/beads-{bead-id}/plan.md
   ```
   - Understand current structure, phases, scope
   - Note success criteria and approach

2. **Read the bead for context**:
   ```bash
   bd show {bead-id}
   ```

3. **Understand requested changes**:
   - Parse what user wants to add/modify/remove
   - Identify if changes require codebase research

### Step 2: Research If Needed

**Only if changes require new technical understanding:**

1. **Spawn parallel research tasks**:
   - **codebase-locator**: Find relevant files
   - **codebase-analyzer**: Understand implementation details
   - **codebase-pattern-finder**: Find similar patterns

2. **Be specific about directories** in prompts

3. **Wait for ALL tasks** before proceeding

### Step 3: Present Understanding

Before making changes:

```
Based on your feedback, I understand you want to:
- {Change 1 with specific detail}
- {Change 2 with specific detail}

{If research was needed:}
My research found:
- {Relevant discovery}
- {Important constraint}

I plan to update the plan by:
1. {Specific modification}
2. {Another modification}

Does this align with your intent?
```

Get user confirmation before proceeding.

### Step 4: Update the Plan

1. **Make focused, precise edits**:
   - Use Edit tool for surgical changes
   - Maintain existing structure unless explicitly changing it
   - Keep file:line references accurate

2. **Ensure consistency**:
   - New phases follow existing pattern
   - Update "What We're NOT Doing" if scope changes
   - Maintain automated vs manual success criteria distinction

3. **Update plan metadata**:
   - Update frontmatter `date` to current timestamp
   - Add `iteration: {N}` to frontmatter
   - Add `iteration_reason: "{brief description}"` to frontmatter

4. **Preserve completed work**:
   - Don't uncheck items that were already completed
   - If changing completed phases, discuss with user first

### Step 5: Save Iteration History (Optional)

For significant changes, save the previous version:

```bash
cp thoughts/beads-{bead-id}/plan.md thoughts/beads-{bead-id}/plan-v{N}.md
```

Then update the main plan.

### Step 6: Update Bead

```bash
bd update {bead-id} --notes="Plan iterated: {brief description of changes}"
```

### Step 7: Present Changes

```
I've updated the plan at `thoughts/beads-{bead-id}/plan.md`

Changes made:
- {Specific change 1}
- {Specific change 2}

The updated plan now:
- {Key improvement}
- {Another improvement}

Would you like any further adjustments?
```

## Important Guidelines

1. **Be Skeptical**:
   - Don't blindly accept changes that seem problematic
   - Question vague feedback - ask for clarification
   - Point out conflicts with existing phases

2. **Be Surgical**:
   - Make precise edits, not wholesale rewrites
   - Preserve good content that doesn't need changing
   - Only research what's necessary

3. **Be Thorough**:
   - Read entire plan before making changes
   - Ensure updated sections maintain quality
   - Verify success criteria are still measurable

4. **Be Interactive**:
   - Confirm understanding before making changes
   - Allow course corrections
   - Don't disappear into research without communicating

5. **No Open Questions**:
   - If changes raise questions, ASK
   - Don't update plan with unresolved questions

## Success Criteria Guidelines

When updating success criteria, maintain two categories:

**Automated Verification**:
- Commands: `make test`, `npm run lint`
- Prefer `make` commands when available
- File existence checks

**Manual Verification**:
- UI/UX functionality
- Performance under real conditions
- Edge cases hard to automate

## Handling Major Changes

If feedback requires significant restructuring:

1. **Discuss scope** before proceeding
2. **Consider if this should be a new plan** instead of iteration
3. **Preserve the original** in `plan-v{N}.md`
4. **Update bead description** if scope changed significantly

## Example Invocations

**With full context**:
```
User: /beads:iterate nixos-configs-abc123 - add error handling phase
Assistant: Based on your feedback, I understand you want to add a new phase for error handling...
```

**Interactive**:
```
User: /beads:iterate nixos-configs-abc123
Assistant: I've found the plan. What changes would you like to make?
User: Split Phase 2 into backend and frontend phases
Assistant: I'll split Phase 2 into two separate phases...
```