fraim-framework 2.0.56 → 2.0.58

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

@@ -1,562 +0,0 @@
-# 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
-   npm test
-   
-   # Run E2E tests if available
-   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
-npm test
-
-# Run specific test
-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