Cycles/.cursor/rules/enhanced-task-list.mdc

---
description: Enhanced task list management with quality gates and iterative workflow integration
globs: 
alwaysApply: false
---

# Rule: Enhanced Task List Management

## Goal
Manage task lists with integrated quality gates and iterative workflow to prevent context loss and ensure sustainable development.

## Task Implementation Protocol

### Pre-Implementation Check
Before starting any sub-task:
- [ ] **Context Review**: Have you reviewed CONTEXT.md and relevant documentation?
- [ ] **Pattern Identification**: Do you understand existing patterns to follow?
- [ ] **Integration Planning**: Do you know how this will integrate with existing code?
- [ ] **Size Validation**: Is this task small enough (≤50 lines, ≤250 lines per file)?

### Implementation Process
1. **One sub-task at a time**: Do **NOT** start the next sub‑task until you ask the user for permission and they say "yes" or "y"
2. **Step-by-step execution**: 
   - Plan the approach in bullet points
   - Wait for approval
   - Implement the specific sub-task
   - Test the implementation
   - Update documentation if needed
3. **Quality validation**: Run through the code review checklist before marking complete

### Completion Protocol
When you finish a **sub‑task**:
1. **Immediate marking**: Change `[ ]` to `[x]` 
2. **Quality check**: Verify the implementation meets quality standards
3. **Integration test**: Ensure new code works with existing functionality
4. **Documentation update**: Update relevant files if needed
5. **Parent task check**: If **all** subtasks underneath a parent task are now `[x]`, also mark the **parent task** as completed
6. **Stop and wait**: Get user approval before proceeding to next sub-task

## Enhanced Task List Structure

### Task File Header
```markdown
# Task List: [Feature Name]

**Source PRD**: `prd-[feature-name].md`
**Status**: In Progress / Complete / Blocked
**Context Last Updated**: [Date]
**Architecture Review**: Required / Complete / N/A

## Quick Links
- [Context Documentation](./CONTEXT.md)
- [Architecture Guidelines](./docs/architecture.md)
- [Related Files](#relevant-files)
```

### Task Format with Quality Gates
```markdown
- [ ] 1.0 Parent Task Title
  - **Quality Gate**: Architecture review required
  - **Dependencies**: List any dependencies
  - [ ] 1.1 [Sub-task description 1.1]
    - **Size estimate**: [Small/Medium/Large]
    - **Pattern reference**: [Reference to existing pattern]
    - **Test requirements**: [Unit/Integration/Both]
  - [ ] 1.2 [Sub-task description 1.2]
    - **Integration points**: [List affected components]
    - **Risk level**: [Low/Medium/High]
```

## Relevant Files Management

### Enhanced File Tracking
```markdown
## Relevant Files

### Implementation Files
- `path/to/file1.ts` - Brief description of purpose and role
  - **Status**: Created / Modified / Needs Review
  - **Last Modified**: [Date]
  - **Review Status**: Pending / Approved / Needs Changes

### Test Files  
- `path/to/file1.test.ts` - Unit tests for file1.ts
  - **Coverage**: [Percentage or status]
  - **Last Run**: [Date and result]

### Documentation Files
- `docs/module-name.md` - Module documentation
  - **Status**: Up to date / Needs update / Missing
  - **Last Updated**: [Date]

### Configuration Files
- `config/setting.json` - Configuration changes
  - **Environment**: [Dev/Staging/Prod affected]
  - **Backup**: [Location of backup]
```

## Task List Maintenance

### During Development
1. **Regular updates**: Update task status after each significant change
2. **File tracking**: Add new files as they are created or modified
3. **Dependency tracking**: Note when new dependencies between tasks emerge
4. **Risk assessment**: Flag tasks that become more complex than anticipated

### Quality Checkpoints
At 25%, 50%, 75%, and 100% completion:
- [ ] **Architecture alignment**: Code follows established patterns
- [ ] **Performance impact**: No significant performance degradation
- [ ] **Security review**: No security vulnerabilities introduced
- [ ] **Documentation current**: All changes are documented

### Weekly Review Process
1. **Completion assessment**: What percentage of tasks are actually complete?
2. **Quality assessment**: Are completed tasks meeting quality standards?
3. **Process assessment**: Is the iterative workflow being followed?
4. **Risk assessment**: Are there emerging risks or blockers?

## Task Status Indicators

### Status Levels
- `[ ]` **Not Started**: Task not yet begun
- `[~]` **In Progress**: Currently being worked on  
- `[?]` **Blocked**: Waiting for dependencies or decisions
- `[!]` **Needs Review**: Implementation complete but needs quality review
- `[x]` **Complete**: Finished and quality approved

### Quality Indicators
- ✅ **Quality Approved**: Passed all quality gates
- ⚠️ **Quality Concerns**: Has issues but functional
- ❌ **Quality Failed**: Needs rework before approval
- 🔄 **Under Review**: Currently being reviewed

### Integration Status
- 🔗 **Integrated**: Successfully integrated with existing code
- 🔧 **Integration Issues**: Problems with existing code integration
- ⏳ **Integration Pending**: Ready for integration testing

## Emergency Procedures

### When Tasks Become Too Complex
If a sub-task grows beyond expected scope:
1. **Stop implementation** immediately
2. **Document current state** and what was discovered
3. **Break down** the task into smaller pieces
4. **Update task list** with new sub-tasks
5. **Get approval** for the new breakdown before proceeding

### When Context is Lost
If AI seems to lose track of project patterns:
1. **Pause development**
2. **Review CONTEXT.md** and recent changes
3. **Update context documentation** with current state
4. **Restart** with explicit pattern references
5. **Reduce task size** until context is re-established

### When Quality Gates Fail
If implementation doesn't meet quality standards:
1. **Mark task** with `[!]` status
2. **Document specific issues** found
3. **Create remediation tasks** if needed
4. **Don't proceed** until quality issues are resolved

## AI Instructions Integration

### Context Awareness Commands
```markdown
**Before starting any task, run these checks:**
1. @CONTEXT.md - Review current project state
2. @architecture.md - Understand design principles  
3. @code-review.md - Know quality standards
4. Look at existing similar code for patterns
```

### Quality Validation Commands
```markdown
**After completing any sub-task:**
1. Run code review checklist
2. Test integration with existing code
3. Update documentation if needed
4. Mark task complete only after quality approval
```

### Workflow Commands
```markdown
**For each development session:**
1. Review incomplete tasks and their status
2. Identify next logical sub-task to work on
3. Check dependencies and blockers
4. Follow iterative workflow process
5. Update task list with progress and findings
```

## Success Metrics

### Daily Success Indicators
- Tasks are completed according to quality standards
- No sub-tasks are started without completing previous ones
- File tracking remains accurate and current
- Integration issues are caught early

### Weekly Success Indicators  
- Overall task completion rate is sustainable
- Quality issues are decreasing over time
- Context loss incidents are rare
- Team confidence in codebase remains high