Cycles/.cursor/rules/iterative-workflow.mdc

---
description: Iterative development workflow for AI-assisted coding
globs: 
alwaysApply: false
---

# Rule: Iterative Development Workflow

## Goal
Establish a structured, iterative development process that prevents the chaos and complexity that can arise from uncontrolled AI-assisted development.

## Development Phases

### Phase 1: Planning and Design
**Before writing any code:**

1. **Understand the Requirement**
   - Break down the task into specific, measurable objectives
   - Identify existing code patterns that should be followed
   - List dependencies and integration points
   - Define acceptance criteria

2. **Design Review**
   - Propose approach in bullet points
   - Wait for explicit approval before proceeding
   - Consider how the solution fits existing architecture
   - Identify potential risks and mitigation strategies

### Phase 2: Incremental Implementation
**One small piece at a time:**

1. **Micro-Tasks** (≤ 50 lines each)
   - Implement one function or small class at a time
   - Test immediately after implementation
   - Ensure integration with existing code
   - Document decisions and patterns used

2. **Validation Checkpoints**
   - After each micro-task, verify it works correctly
   - Check that it follows established patterns
   - Confirm it integrates cleanly with existing code
   - Get approval before moving to next micro-task

### Phase 3: Integration and Testing
**Ensuring system coherence:**

1. **Integration Testing**
   - Test new code with existing functionality
   - Verify no regressions in existing features
   - Check performance impact
   - Validate error handling

2. **Documentation Update**
   - Update relevant documentation
   - Record any new patterns or decisions
   - Update context files if architecture changed

## Iterative Prompting Strategy

### Step 1: Context Setting
```
Before implementing [feature], help me understand:
1. What existing patterns should I follow?
2. What existing functions/classes are relevant?
3. How should this integrate with [specific existing component]?
4. What are the potential architectural impacts?
```

### Step 2: Plan Creation
```
Based on the context, create a detailed plan for implementing [feature]:
1. Break it into micro-tasks (≤50 lines each)
2. Identify dependencies and order of implementation
3. Specify integration points with existing code
4. List potential risks and mitigation strategies

Wait for my approval before implementing.
```

### Step 3: Incremental Implementation
```
Implement only the first micro-task: [specific task]
- Use existing patterns from [reference file/function]
- Keep it under 50 lines
- Include error handling
- Add appropriate tests
- Explain your implementation choices

Stop after this task and wait for approval.
```

## Quality Gates

### Before Each Implementation
- [ ] **Purpose is clear**: Can explain what this piece does and why
- [ ] **Pattern is established**: Following existing code patterns
- [ ] **Size is manageable**: Implementation is small enough to understand completely
- [ ] **Integration is planned**: Know how it connects to existing code

### After Each Implementation
- [ ] **Code is understood**: Can explain every line of implemented code
- [ ] **Tests pass**: All existing and new tests are passing
- [ ] **Integration works**: New code works with existing functionality
- [ ] **Documentation updated**: Changes are reflected in relevant documentation

### Before Moving to Next Task
- [ ] **Current task complete**: All acceptance criteria met
- [ ] **No regressions**: Existing functionality still works
- [ ] **Clean state**: No temporary code or debugging artifacts
- [ ] **Approval received**: Explicit go-ahead for next task
- [ ] **Documentaion updated**: If relevant changes to module was made.

## Anti-Patterns to Avoid

### Large Block Implementation
**Don't:**
```
Implement the entire user management system with authentication, 
CRUD operations, and email notifications.
```

**Do:**
```
First, implement just the User model with basic fields.
Stop there and let me review before continuing.
```

### Context Loss
**Don't:**
```
Create a new authentication system.
```

**Do:**
```
Looking at the existing auth patterns in auth.py, implement 
password validation following the same structure as the 
existing email validation function.
```

### Over-Engineering
**Don't:**
```
Build a flexible, extensible user management framework that 
can handle any future requirements.
```

**Do:**
```
Implement user creation functionality that matches the existing 
pattern in customer.py, focusing only on the current requirements.
```

## Progress Tracking

### Task Status Indicators
- 🔄 **In Planning**: Requirements gathering and design
- ⏳ **In Progress**: Currently implementing
- ✅ **Complete**: Implemented, tested, and integrated
- 🚫 **Blocked**: Waiting for decisions or dependencies
- 🔧 **Needs Refactor**: Working but needs improvement

### Weekly Review Process
1. **Progress Assessment**
   - What was completed this week?
   - What challenges were encountered?
   - How well did the iterative process work?

2. **Process Adjustment**
   - Were task sizes appropriate?
   - Did context management work effectively?
   - What improvements can be made?

3. **Architecture Review**
   - Is the code remaining maintainable?
   - Are patterns staying consistent?
   - Is technical debt accumulating?

## Emergency Procedures

### When Things Go Wrong
If development becomes chaotic or problematic:

1. **Stop Development**
   - Don't continue adding to the problem
   - Take time to assess the situation
   - Don't rush to "fix" with more AI-generated code

2. **Assess the Situation**
   - What specific problems exist?
   - How far has the code diverged from established patterns?
   - What parts are still working correctly?

3. **Recovery Process**
   - Roll back to last known good state
   - Update context documentation with lessons learned
   - Restart with smaller, more focused tasks
   - Get explicit approval for each step of recovery

### Context Recovery
When AI seems to lose track of project patterns:

1. **Context Refresh**
   - Review and update CONTEXT.md
   - Include examples of current code patterns
   - Clarify architectural decisions

2. **Pattern Re-establishment**
   - Show AI examples of existing, working code
   - Explicitly state patterns to follow
   - Start with very small, pattern-matching tasks

3. **Gradual Re-engagement**
   - Begin with simple, low-risk tasks
   - Verify pattern adherence at each step
   - Gradually increase task complexity as consistency returns

## Success Metrics

### Short-term (Daily)
- Code is understandable and well-integrated
- No major regressions introduced
- Development velocity feels sustainable
- Team confidence in codebase remains high

### Medium-term (Weekly)
- Technical debt is not accumulating
- New features integrate cleanly
- Development patterns remain consistent
- Documentation stays current

### Long-term (Monthly)
- Codebase remains maintainable as it grows
- New team members can understand and contribute
- AI assistance enhances rather than hinders development
- Architecture remains clean and purposeful