fraim-framework 2.0.66 → 2.0.67

package/dist/registry/workflows/quality-assurance/iterative-improvement-cycle.md

@@ -0,0 +1,562 @@
+# Iterative Improvement Cycle Workflow
+
+## INTENT
+To systematically improve application quality through iterative cycles of Review → Critique → Fix → Validate, ensuring high-quality, production-ready applications.
+
+## PRINCIPLES
+- **Systematic Review**: Thorough examination of all aspects
+- **Honest Critique**: Identifying issues without bias
+- **Targeted Fixes**: Addressing issues one at a time
+- **Validation**: Verifying fixes work before moving on
+- **Iteration**: Repeating until satisfied
+
+## Philosophy
+**"Perfect is the enemy of good, but good can always be better."**
+
+This workflow emphasizes:
+- **Systematic Review**: Thorough examination of all aspects
+- **Honest Critique**: Identifying issues without bias
+- **Targeted Fixes**: Addressing issues one at a time
+- **Validation**: Verifying fixes work before moving on
+- **Iteration**: Repeating until satisfied
+
+## Prerequisites
+- Application is functional (even if basic)
+- Server running locally or deployed
+- Browser testing tools available
+- Git repository for tracking changes
+- Test suite (optional but recommended)
+
+## When to Use This Workflow
+
+Use this workflow after implementation (`workflows/implement.md`) to:
+- Validate that implemented features work correctly
+- Identify and fix issues discovered during testing
+- Improve quality through systematic review
+- Ensure production readiness
+
+This workflow complements:
+- `workflows/implement.md` - Post-implementation validation
+- `workflows/test.md` - Testing and validation
+- `workflows/quality-assurance/browser-validation.md` - Browser-specific testing
+
+## The Core Cycle
+
+```
+┌─────────────┐
+│   REVIEW    │ ← Start here: Examine the application
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   CRITIQUE  │ ← Identify issues, improvements, gaps
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│     FIX     │ ← Address issues systematically
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  VALIDATE   │ ← Verify fixes work, check for regressions
+└──────┬──────┘
+       │
+       └───→ REPEAT until satisfied
+```
+
+## Phase 1: Initial Review
+
+### 1.1 Start the Application
+```bash
+# Start server in watch mode (if available)
+npm run dev:server  # or equivalent
+
+# Start client in watch mode
+npm run dev  # or equivalent
+
+# Verify both are running
+curl http://localhost:5000/api/health
+# Open browser to http://localhost:3000 (or configured port)
+```
+
+### 1.2 Systematic Page Review
+Navigate through **every page** in the application:
+
+1. **Homepage/Landing Page**
+   - [ ] Loads correctly
+   - [ ] Navigation works
+   - [ ] Content displays properly
+   - [ ] Links are functional
+   - [ ] Images load
+   - [ ] Responsive design works
+
+2. **Core Feature Pages**
+   - [ ] All main feature pages accessible
+   - [ ] Primary functionality works
+   - [ ] Data displays correctly
+   - [ ] User interactions work
+
+3. **Secondary Pages**
+   - [ ] About/Help pages
+   - [ ] Contact/Support pages
+   - [ ] Documentation pages
+   - [ ] Any other informational pages
+
+4. **Authentication Pages** (if applicable)
+   - [ ] Login page
+   - [ ] Sign up/Registration page
+   - [ ] Password reset (if applicable)
+   - [ ] Account recovery (if applicable)
+
+5. **Protected Pages** (if applicable)
+   - [ ] Dashboard (when authenticated)
+   - [ ] Create/Edit pages (when authorized)
+   - [ ] Admin pages (if applicable)
+   - [ ] User profile/settings pages
+
+### 1.3 Feature Testing
+For each major feature:
+- [ ] Can I complete the primary use case?
+- [ ] Does data persist correctly?
+- [ ] Are error messages helpful?
+- [ ] Is the UI intuitive?
+- [ ] Are loading states shown?
+- [ ] Do success/error notifications appear?
+
+### 1.4 Data Validation
+- [ ] Are database objects displayed correctly?
+- [ ] Is seed/test data showing up (if applicable)?
+- [ ] Can I create new data?
+- [ ] Can I edit existing data?
+- [ ] Can I delete data (if applicable)?
+- [ ] Are relationships between data correct?
+
+### 1.5 UI/UX Review
+- [ ] Is the design consistent?
+- [ ] Are colors and fonts appropriate?
+- [ ] Is spacing consistent?
+- [ ] Are buttons clearly labeled?
+- [ ] Are forms easy to fill out?
+- [ ] Is navigation intuitive?
+- [ ] Are error states handled gracefully?
+- [ ] Are empty states informative?
+
+## Phase 2: Critique & Issue Identification
+
+### 2.1 Create Issue Categories
+Organize findings into categories:
+
+**Critical Issues** (Blocks functionality)
+- Features that don't work at all
+- Data loss or corruption
+- Security vulnerabilities
+- Broken authentication
+
+**High Priority** (Major problems)
+- Features that work but have significant issues
+- Poor user experience
+- Missing essential functionality
+- Performance problems
+
+**Medium Priority** (Improvements needed)
+- UI/UX polish needed
+- Minor functionality gaps
+- Inconsistent behavior
+- Missing edge case handling
+
+**Low Priority** (Nice to have)
+- Visual polish
+- Minor text improvements
+- Additional features
+- Optimization opportunities
+
+### 2.2 Issue Documentation Template
+For each issue, create a structured entry. Use GitHub Issues or track in a document:
+
+```markdown
+## Issue: [Clear, descriptive title]
+
+**Category**: [Critical/High/Medium/Low]
+**Type**: [Functionality/UI/UX/Data/Performance/Security]
+**Page/Feature**: [Where it occurs]
+**Use Case**: [Related use case if applicable]
+
+**Description**:
+[Clear description of the issue]
+
+**Steps to Reproduce**:
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Expected Behavior**:
+[What should happen]
+
+**Actual Behavior**:
+[What actually happens]
+
+**Screenshot/Evidence**:
+[If applicable]
+
+**Impact**:
+[Who is affected and how]
+
+**Proposed Fix**:
+[Initial thoughts on how to fix]
+```
+
+### 2.3 Create Git Issues
+For each identified issue:
+1. Create a GitHub issue (or equivalent)
+2. Use the documentation template
+3. Add appropriate labels
+4. Link to related use cases
+5. Set priority
+
+**Example Issue Creation**:
+```bash
+# Using GitHub CLI
+gh issue create \
+  --title "Issue description" \
+  --body "$(cat issue-template.md)" \
+  --label "bug,high-priority"
+```
+
+## Phase 3: Systematic Fixes
+
+### 3.1 Prioritization Order
+Fix issues in this order:
+1. **Critical** - Fix immediately
+2. **High** - Fix before next iteration
+3. **Medium** - Fix in batches
+4. **Low** - Fix if time permits
+
+### 3.2 Fix Process for Each Issue
+
+Follow the standard implementation workflow (`workflows/implement.md`) for each fix:
+
+#### Step 1: Reproduce Locally
+```bash
+# Ensure server is running
+npm run dev:server
+
+# Ensure client is running  
+npm run dev
+
+# Reproduce the issue in browser
+# Document exact steps
+```
+
+#### Step 2: Identify Root Cause
+- Check browser console for errors
+- Check server logs
+- Review relevant code
+- Check database state
+- Verify API responses
+
+#### Step 3: Implement Fix
+- Make minimal, targeted changes
+- Follow existing code patterns
+- Add comments if needed
+- Don't fix unrelated issues (unless explicitly asked)
+- Follow `workflows/implement.md` guidelines
+
+#### Step 4: Write/Update Tests
+- Write tests for the fix following `workflows/test.md`
+- Update existing tests if needed
+- Run test suite to ensure all pass
+
+#### Step 5: Verify Fix Locally
+- Test the specific fix
+- Test related functionality
+- Check for regressions
+- Verify in browser
+
+#### Step 6: Commit Fix
+```bash
+git add -A
+git commit -m "fix: [clear description of what was fixed]
+
+- [Specific change 1]
+- [Specific change 2]
+- [Related changes]
+
+Fixes #[issue-number]"
+```
+
+### 3.3 Fix Checklist
+For each fix:
+- [ ] Issue reproduced locally
+- [ ] Root cause identified
+- [ ] Fix implemented (following `workflows/implement.md`)
+- [ ] Tests written/updated (following `workflows/test.md`)
+- [ ] Tests pass
+- [ ] Fix verified in browser
+- [ ] No regressions introduced
+- [ ] Code committed with clear message
+- [ ] Issue updated/closed
+
+## Phase 4: Validation
+
+### 4.1 Immediate Validation (After Each Fix)
+After fixing an issue:
+1. **Test the specific fix**
+   - Does the issue no longer occur?
+   - Does the feature work as expected?
+
+2. **Test related functionality**
+   - Did the fix break anything else?
+   - Are related features still working?
+
+3. **Check for regressions**
+   - Run existing tests
+   - Manually test related features
+   - Check browser console for errors
+
+4. **Update issue status**
+   ```bash
+   gh issue close #[number] --comment "Fixed and validated"
+   ```
+
+### 4.2 Comprehensive Validation (After Batch of Fixes)
+After fixing multiple issues:
+
+1. **Re-run Full Review**
+   - Go through Phase 1 again
+   - Check all pages
+   - Test all features
+   - Verify data integrity
+
+2. **Test Suite Validation**
+   ```bash
+   # Run all tests
+   npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- npm test
+   
+   # Run E2E tests if available
+   npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 180 -- npm run test:e2e
+   
+   # Ensure all pass
+   ```
+
+3. **Browser Validation**
+   See also: `workflows/quality-assurance/browser-validation.md`
+   - Test in Chrome
+   - Test in Firefox (if time permits)
+   - Test on mobile (responsive)
+   - Check console for errors
+
+4. **Deployment Validation** (if applicable)
+   See also: `workflows/deploy/cloud-deployment.md`
+   - Deploy to staging/production
+   - Validate fixes work in production
+   - Check production logs
+   - Monitor for errors
+
+## Phase 5: Iteration Decision
+
+### 5.1 Assessment Criteria
+After each cycle, assess:
+
+**Continue Iterating If:**
+- Critical issues remain
+- High-priority issues remain
+- User experience is poor
+- Core functionality is broken
+- You're not satisfied with quality
+
+**Stop Iterating If:**
+- All critical issues fixed
+- All high-priority issues fixed
+- Application is stable
+- User experience is good
+- You're satisfied with quality
+- Time/budget constraints
+
+### 5.2 Next Iteration Planning
+If continuing:
+1. Review remaining issues
+2. Prioritize for next cycle
+3. Plan fix order
+4. Estimate effort
+5. Begin Phase 1 again
+
+### 5.3 Final Validation
+If stopping:
+1. Complete final comprehensive review
+2. Run full test suite
+3. Validate in production (if deployed)
+4. Document any known issues
+5. Create summary report
+
+## Phase 6: Documentation & Handoff
+
+### 6.1 Create Improvement Report
+Document the iteration cycle. Use evidence templates retrieved via `get_fraim_file({ path: "templates/evidence/..." })`:
+
+```markdown
+# Iterative Improvement Report
+
+## Iteration Summary
+- **Total Iterations**: [number]
+- **Issues Found**: [number]
+- **Issues Fixed**: [number]
+- **Remaining Issues**: [number]
+
+## Issues Fixed
+[Detailed list of all fixes]
+
+## Remaining Issues
+[Any issues not yet fixed]
+
+## Test Coverage
+- Unit tests: [coverage %]
+- Integration tests: [count]
+- E2E tests: [count]
+
+## Final Status
+- [ ] All critical issues resolved
+- [ ] Application is stable
+- [ ] User experience is good
+- [ ] Ready for production
+```
+
+### 6.2 Update Related Documentation
+- Update README if needed
+- Update deployment docs if changed
+- Update test documentation
+- Update use case documentation (if applicable)
+
+## Best Practices
+
+### 1. Focus on One Issue at a Time
+- Don't try to fix everything at once
+- Complete one fix fully before moving to next
+- Verify each fix before proceeding
+
+### 2. Keep Fixes Small and Targeted
+- Make minimal changes
+- Don't refactor unnecessarily
+- Don't fix unrelated issues
+- Follow `workflows/implement.md` principles
+
+### 3. Always Validate
+- Never skip validation
+- Test in browser after each fix
+- Run tests after each fix
+- Check for regressions
+
+### 4. Document Everything
+- Document issues clearly
+- Document fixes clearly
+- Update tests
+- Update documentation
+- Use evidence templates retrieved via `get_fraim_file({ path: "templates/evidence/..." })`
+
+### 5. Use Git Effectively
+- Commit after each fix
+- Write clear commit messages
+- Link commits to issues
+- Keep commits focused
+
+### 6. Iterate Quickly
+- Short cycles are better than long ones
+- Fix, validate, move on
+- Don't overthink
+- Don't over-engineer
+
+## Common Patterns
+
+### Pattern 1: UI/UX Issues
+```
+Review → Identify styling/layout issues → Fix CSS/styling → Validate in browser → Iterate
+```
+
+### Pattern 2: Functionality Issues
+```
+Review → Identify broken feature → Debug → Fix code (follow workflows/implement.md) → Write test (follow workflows/test.md) → Validate → Iterate
+```
+
+### Pattern 3: Data Issues
+```
+Review → Identify data problems → Check database → Fix seed/data → Validate → Iterate
+```
+
+### Pattern 4: Performance Issues
+```
+Review → Identify slow features → Profile → Optimize → Validate → Iterate
+```
+
+## Tools & Commands
+
+### Development
+```bash
+# Start server in watch mode
+npm run dev:server  # or equivalent
+
+# Start client in watch mode
+npm run dev  # or equivalent
+
+# Run tests
+npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- npm test
+
+# Run specific test
+npx tsx ~/.fraim/scripts/exec-with-timeout.ts --timeout 120 -- npm test -- [test-file]
+
+# Build for production
+npm run build
+```
+
+### Validation
+```bash
+# Check server health
+curl http://localhost:5000/api/health  # adjust port as needed
+
+# Check API endpoints
+curl http://localhost:5000/api/[endpoint]  # adjust as needed
+
+# Run linter
+npm run lint
+
+# Type check
+npm run type-check
+```
+
+## Success Criteria
+
+An iteration cycle is successful when:
+- ✅ All identified issues are fixed
+- ✅ All fixes are validated
+- ✅ No regressions introduced
+- ✅ Tests pass
+- ✅ Application is stable
+- ✅ User experience is good
+- ✅ Ready for next iteration or production
+
+## Related Workflows
+- `workflows/implement.md` - Implementation workflow to follow when fixing issues
+- `workflows/test.md` - Testing workflow for writing and running tests
+- `workflows/quality-assurance/browser-validation.md` - Detailed browser testing
+- `workflows/deploy/cloud-deployment.md` - Deployment validation
+- Retrieve via `get_fraim_file({ path: "templates/evidence/..." })` - Evidence templates for documentation
+
+## Notes for Future Agents
+
+1. **Don't skip steps** - Each phase is important
+2. **Be thorough** - Review everything systematically
+3. **Be honest** - Don't ignore issues
+4. **Be focused** - Fix one thing at a time
+5. **Always validate** - Never assume fixes work
+6. **Iterate until satisfied** - Quality takes multiple passes
+7. **Document everything** - Future you will thank you
+8. **Follow existing workflows** - Use `workflows/implement.md` and `workflows/test.md` for fixes
+
+## Output Artifacts
+
+After completing this workflow, you should have:
+1. **Issue Log** - All issues found and fixed
+2. **Improvement Report** - Summary of iterations (using evidence templates)
+3. **Test Results** - All tests passing
+4. **Validation Report** - Browser validation results
+5. **Git History** - Clear commit history of fixes
+6. **Updated Documentation** - Any docs that changed