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

description, model

description	model
Iterate on existing implementation plans for a bead issue	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:

   cat thoughts/beads-{bead-id}/plan.md
   

   • Understand current structure, phases, scope
   • Note success criteria and approach

2. Read the bead for context:

   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:

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

Then update the main plan.

Step 6: Update Bead

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...