fraim-framework 2.0.36 → 2.0.38

package/registry/workflows/product-building/retrospect.md

@@ -1,86 +0,0 @@
-# Retrospective Creation
-
-## INTENT
-To capture learnings and insights from completed issues, enabling continuous improvement and preventing future similar problems through systematic analysis and documentation.
-
-## PRINCIPLES
-- **Success Criteria**: Focus on Integrity (Self-reflection) and Independence (Learning from mistakes) - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- Every completed issue requires a retrospective
-- Focus on root causes, not just symptoms
-- Document both successes and failures
-- Create actionable prevention measures
-- Share learnings with other agents
-- Continuous Learning: Follow "Continuous Learning" principles (read `rules/continuous-learning.md` via `get_fraim_file`)
-
-## WORKFLOW
-
-1. **Label the issue** `status:wip` and remove `status:complete`
-2. **Create retrospective document** using the template
-3. **Complete retrospective** following the quality checklist
-4. **When ready for review**, flip issue to `status:needs-review` and remove `status:wip`
-5. **Iterate** until the PR is approved
-
-## RETROSPECTIVE TRIGGERS
-
-- **All Issues**: Every completed issue requires a retrospective
-- **Complex Issues (>3 iterations)**: Must create detailed retrospective
-- **Process Violations**: Any workflow rule violations require detailed retrospectives
-- **Work Loss Incidents**: Any incidents where work is lost require detailed retrospectives
-
-## RETROSPECTIVE CREATION PROCESS
-
-### 1. Create Retrospective File
-- **File path**: `retrospectives/issue-{issue-number}-{kebab-title}-postmortem.md`
-- **Template**: Use Retrospective template: `get_fraim_file({ path: "templates/retrospective/RETROSPECTIVE-TEMPLATE.md" })`
-- **Copy template**: Copy the template file and fill in the placeholders
-
-### 2. Root Cause Analysis
-- Identify underlying causes, not just symptoms
-- Document what went wrong and why
-- Analyze process failures and human errors
-- Look for patterns that could affect other issues
-
-### 3. Prevention Measures
-- Document specific actions to prevent recurrence
-- Update rules and workflows based on learnings
-- Share solutions with other agents through issue comments
-- Identify process improvements
-
-### 4. Document Success Factors
-- What worked well and why
-- Best practices discovered
-- Tools and techniques that helped
-- Lessons that can be applied to future issues
-
-## RETROSPECTIVE QUALITY CHECKLIST
-
-Before marking retrospective complete, verify:
-- [ ] Root cause analysis completed (not just symptoms)
-- [ ] Prevention measures documented
-- [ ] Process improvements identified
-- [ ] Success factors captured
-- [ ] Action items are specific and actionable
-- [ ] Template followed completely
-- [ ] File saved in correct location
-- [ ] All placeholders replaced with actual content
-- [ ] Timeline of events is accurate and complete
-- [ ] Lessons learned are actionable
-
-## EXAMPLES
-
-### Good: Comprehensive Retrospective
-```
-- Root cause: "Agent didn't verify workspace directory before file operations"
-- Prevention: "Added mandatory pwd check before any file operation"
-- Learning: "Workspace violations are common without explicit safeguards"
-- Git Issues Suggested: "Update local-development.mdc with verification checklist"
-```
-
-### Bad: Surface-Level Retrospective
-```
-- Problem: "File created in wrong location"
-- Solution: "Moved file to correct location"
-- Learning: "Need to be more careful"
-```
-
-**CRITICAL**: Do not close the issue until retrospective is created, reviewed, and approved.

package/registry/workflows/product-building/spec.md

@@ -1,117 +0,0 @@
-# Workflow: spec
-
-**Path:** `workflows/spec.md`
-
----
-
-# Specification Phase
-
-## INTENT
-To create comprehensive, detailed product specifications that clarify the Why, What and User Experiences for new features.
-
-## PRINCIPLES
-- **Success Criteria**: Optimize for Integrity, Correctness, Completeness, Independence, and Speed - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **Start with the User**: Understand the user's needs and experiences before implementing
-- **User Experience Matters**: Focus on creating a great user experience right from the beginning
-- **Validation Criteria**: Define clear validation criteria to ensure the feature meets user needs
-- **Simplicity**: Maintain simplicity in feature definition (read `rules/simplicity.md` via `get_fraim_file`)
-
-## SPECIFICATION WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug}). Get slug details using GitHub MCP.
-
-### Step 2: Phase Initiation
-Label the issue 'phase:spec' (GitHub Action will automatically create a draft PR if none exists, or update the existing PR with phase-specific details, and label the issue `status:wip`)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Pushed the empty branch to origin
-- ✅ Indexed the codebase with Serena
-- ✅ Opened the editor in the prepared workspace
-
-You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
-
-### Step 4: Work Location
-You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working.
-
-### Step 5: Pre-Creation Validation
-Before creating any specification document, agents MUST:
-
-1. **Verify Template Selection**:
-   - Use Feature Spec template: `get_fraim_file({ path: "templates/specs/FEATURESPEC-TEMPLATE.md" })`
-   
-2. **Validate Naming Convention**:
-   - Format: `docs/feature specs/{issue_number}-{kebab-title}.md`
-   - Example: `docs/feature specs/228-improve-token-refresh.md`
-   - NO other naming patterns allowed
-
-3. **Template Compliance Check**:
-   - Read and understand the template first
-   
-### Step 6: Specification Document Creation
-
-#### Core Principle: Focus on WHAT and WHY, Not HOW
-**Feature specifications describe the desired outcome and user experience, NOT technical implementation details.**
-
-#### Include:
-- **High-Fidelity Mocks**: All UI changes must include clickable or high-fidelity HTML/CSS mocks. Markdown code blocks are NOT sufficient for UI specifications.
-- Clear user stories and acceptance criteria.
-- Edge cases and error states.
-
-#### Exclude:
-- **Markdown Mocks**: Do NOT use markdown code blocks (e.g. ` ```html `) to mock UI. Use real HTML/CSS files or screenshots.
-- Technical implementation details.
-- Database schema changes (these belong in the Design Phase).
-
-### Step 7: Specification Creation Checklist
-Before committing your work, verify:
-- [ ] Correct template used (`FEATURESPEC-TEMPLATE.md`)
-- [ ] Proper file naming: `docs/feature specs/{issue_number}-{kebab-title}.md`
-- [ ] High-Fidelity mocks included (if UI changes)
-- [ ] No Markdown mocks used for UI
-- [ ] All template sections completed
-- [ ] No placeholder text remaining
-- [ ] Issue labeled `phase:spec`
-- [ ] Working in correct branch
-
-### Step 8: Submit for Review
-- Commit and sync your work
-- Label the issue 'status:needs-review' and remove 'status:wip'
-- Update the PR with a comment to include evidence - Use Spec Evidence template: `get_fraim_file({ path: "templates/evidence/Spec-Evidence.md" })`
-- **Next Step**: Switch to "Iterate on PR Comments" workflow: `get_fraim_file({ path: "workflows/product-building/iterate-on-pr-comments.md" })`
-
-### Step 9: Iteration
-If workflow actions or reviewer feedback indicates more work is needed:
-- Label the issue 'status:wip' and remove 'status:needs-review'
-- Go back to Step 6 and iterate until PR is approved
-
-## EXAMPLES
-
-### Good: Comprehensive Specification Process
-```
-Issue #84: "Add calendar sync"
-1. ✅ Identified: Issue #84, slug: "add-calendar-sync"
-2. ✅ Phase: Set phase:spec, PR created
-3. ✅ Environment: User ran prep-issue.sh, ready to work
-4. ✅ Location: Working in prepared workspace with Serena indexing
-5. ✅ Spec: Created docs/feature specs/84-add-calendar-sync.md
-6. ✅ Mocks: Included high-fidelity HTML mocks for the sync settings
-7. ✅ Review: Set status:needs-review
-8. ✅ Iteration: Incorporated feedback, updated spec
-Result: Clear, user-focused specification with high-fi mocks
-```
-
-### Bad: Incomplete Specification Process
-```
-Issue #84: "Add calendar sync"
-1. ✅ Identified: Issue #84
-2. ❌ Skip: Didn't set phase:spec
-3. ❌ Skip: Didn't create branch
-4. ❌ Skip: Started coding without spec
-5. ❌ Skip: No spec document created
-6. ❌ Skip: Used simple markdown mocks for complex UI
-Result: Unclear user experience, potential rework
-```

package/registry/workflows/product-building/test.md

@@ -1,120 +0,0 @@
-# Workflow: test
- 
-**Path:** `workflows/test.md`
- 
----
- 
-# Testing Phase
- 
-## INTENT
-To create comprehensive test coverage that accurately reproduces issues and validates solutions, ensuring robust testing through proper test structure, failure verification, and systematic test execution.
- 
-## PRINCIPLES
-- **Success Criteria**: Optimize for Integrity (Honest reporting), Correctness (Coverage), Completeness, Independence, and Speed - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **Test-Driven**: Write tests that reproduce the issue before fixing
-- **Comprehensive Coverage**: Ensure all scenarios are tested
-- **Failure Verification**: Confirm tests fail before implementation
-- **Proper Structure**: Use established test patterns and frameworks
-- **Systematic Execution**: Follow consistent testing procedures
-- **Testing Guidelines**: Follow "Agent Testing Guidelines" (read `rules/agent-testing-guidelines.md` via `get_fraim_file`)
-- **Integrity**: Adhere to "Integrity and Test Ethics" (read `rules/integrity-and-test-ethics.md` via `get_fraim_file`)
-- **Architecture**: Follow existing architecture - see `.fraim/config.json` for the path (`customizations.architectureDoc`)
-
-## TESTING WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug}); confirm target branch feature/{issue_number}-{slug}.
-
-### Step 2: Phase Initiation
-Label the issue 'phase:tests'. (GitHub Action will automatically create a draft PR if none exists, or update the existing PR with phase-specific details, and label the issue `status:wip`)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Pushed the empty branch to origin
-- ✅ Indexed the codebase with Serena
-- ✅ Opened the editor in the prepared workspace
-
-You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
-
-### Step 4: Work Location
-You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working. 
-
-### Step 5: Testing Work
-Your work entails the following:
-
-- Review the RFC associated with this issue.
-- Determine whether tests need to be added to an existing test suite, or a new one needs to be created.
-- **CRITICAL: Write INTEGRATION tests that demonstrate the REAL USER SCENARIO**
-  - Test the actual end-to-end user experience, not unit tests for hypothetical fixes
-  - Use real services and APIs where possible (not mocks)
-  - Verify the issue occurs in the real system as described in the issue
-  - Example: For email threading issues, actually send emails and verify they appear as new messages vs replies
-- **Use Case Mapping**: If working with documented use cases, map each use case to test cases:
-  - For each use case, create corresponding test scenarios (happy path, edge cases, error cases)
-  - Organize tests by use case category
-  - Ensure all high-priority use cases have test coverage
-- Run the test cases to ensure they fail (demonstrating the issue exists)
-- Flip issue to 'status:needs-review' and remove 'status:wip'
-
-### Step 5.1: Robustness & Permutation Testing (MANDATORY)
-**You must author tests that specifically target fragility:**
-
-1.  **Regex Resilience**: if using regex, test for:
-    - Case sensitivity (upper/lower/mixed)
-    - Line endings (`\n` vs `\r\n`)
-    - Whitespace variations
-2.  **Negative & Default State Testing**:
-    - Assert that empty inputs fail (do not silently default)
-    - Assert that fallback values (e.g. "No intent defined") trigger failures
-3.  **Boundary Conditions**:
-    - Test inputs that are too short, too long, or malformed
-4.  **Silent Failure Prevention**:
-    - Ensure your tests *assert content coverage*, not just *existence*. (e.g., `assert(content.length > 20)` instead of `assert(content)`)
-
-**❌ DO NOT:**
-- Write unit tests for code that doesn't exist yet
-- Test hypothetical fixes or solutions
-- Create mock tests that don't use real services
-- Test individual components in isolation
-
-**✅ DO:**
-- Test the complete user workflow end-to-end
-- Use real APIs and services when possible
-- Verify the actual problem described in the issue
-- Verify test fails if product code is removed (No Tautologies)
-- Create tests that will pass AFTER the fix is implemented
-
-### Step 6: Iteration
-If workflow actions or reviewer feedback indicates more work is needed, ensure the issue is set back to `status:wip` and continue working as above.
-
-## EXAMPLES
-
-### Good: Comprehensive Testing Process
-```
-Issue #84: "Fix calendar sync timeout"
-1. ✅ Identified: Issue #84, branch feature/84-fix-sync
-2. ✅ Phase: Set phase:tests, PR created
-3. ✅ Environment: User ran prep-issue.sh, ready to work
-4. ✅ Location: Working in prepared workspace with Serena indexing
-5. ✅ RFC Review: Read docs/rfcs/84-fix-sync-timeout.md
-6. ✅ Analysis: Determined need to add timeout tests
-7. ✅ Test Creation: Added test cases for timeout scenarios
-8. ✅ Failure Verification: Confirmed tests fail before fix
-9. ✅ Review: Set status:needs-review
-10. ✅ Iteration: Incorporated feedback, updated tests
-Result: Comprehensive test coverage with proper structure
-```
-
-### Bad: Incomplete Testing Process
-```
-Issue #84: "Fix calendar sync timeout"
-1. ✅ Identified: Issue #84
-2. ❌ Skip: Didn't review RFC
-3. ❌ Skip: Started testing without understanding requirements
-4. ❌ Skip: No test cases written
-5. ❌ Skip: Didn't verify tests fail
-6. ❌ Skip: No test structure followed
-Result: Incomplete, ineffective testing
-```

package/registry/workflows/quality-assurance/browser-validation.md

@@ -1,221 +0,0 @@
-# Browser Validation Workflow
-
-## INTENT
-To systematically validate the application in a browser, identify issues, and iterate until production-ready through comprehensive browser testing.
-
-## PRINCIPLES
-- **Systematic Testing**: Don't skip steps, test everything
-- **Use Case Driven**: Test based on documented use cases
-- **Cross-Browser**: Validate in multiple browsers
-- **Responsive**: Test on different screen sizes
-- **Iterative**: Fix issues and re-validate
-
-## When to Use This Workflow
-
-Use this workflow to:
-- Validate application after implementation (`workflows/implement.md`)
-- Comprehensive browser testing before deployment
-- Identify browser-specific issues
-- Validate responsive design
-
-This workflow complements:
-- `workflows/quality-assurance/iterative-improvement-cycle.md` - For systematic improvement cycles
-- `workflows/test.md` - For writing automated tests
-- `workflows/deploy/cloud-deployment.md` - For deployment validation
-
-## Prerequisites
-- Application deployed (or running locally)
-- Use case documentation available (if applicable)
-- Browser testing tools (Playwright, Selenium, or manual)
-- Issue tracking system (GitHub Issues, etc.)
-
-## Phase 1: Systematic Browser Testing
-
-### 1.1 Prepare Test Environment
-- Open browser (Chrome, Firefox, Safari)
-- Clear cache and cookies
-- Open developer tools for debugging
-- Prepare test data if needed
-
-### 1.2 Test by Use Case Category
-Follow use case documentation (if available) or test by feature:
-- **Authentication**: Sign up, login, logout, password reset
-- **Core Features**: Main application functionality
-- **Secondary Features**: Supporting features
-- **Edge Cases**: Error scenarios, boundary conditions
-
-### 1.3 Document Findings
-For each test:
-- ✅ Pass: Feature works as expected
-- ⚠️ Minor Issue: Works but has problems
-- ❌ Major Issue: Feature broken or missing
-- 📝 Note: Observations, improvements
-
-## Phase 2: Issue Identification & Documentation
-
-### 2.1 Issue Categories
-Organize issues by type:
-- **Functionality**: Features not working
-- **UI/UX**: Styling, layout, usability issues
-- **Data**: Incorrect data, missing data
-- **Performance**: Slow loading, lag
-- **Accessibility**: A11y issues
-- **Browser Compatibility**: Issues in specific browsers
-
-### 2.2 Issue Documentation Template
-Use GitHub Issues or track in a document:
-
-```markdown
-## Issue: [Title]
-
-**Category**: [Functionality/UI/Data/etc.]
-**Priority**: High/Medium/Low
-**Use Case**: [Related use case]
-**Steps to Reproduce**:
-1. [Step]
-2. [Step]
-**Expected**: [What should happen]
-**Actual**: [What actually happens]
-**Screenshot**: [If applicable]
-**Browser**: [Chrome/Firefox/etc.]
-```
-
-### 2.3 Prioritize Issues
-- **Critical**: Blocks core functionality
-- **High**: Major feature broken
-- **Medium**: Feature works but has problems
-- **Low**: Minor issues, polish
-
-## Phase 3: Iterative Fixes
-
-Follow `workflows/quality-assurance/iterative-improvement-cycle.md` for systematic fixes:
-
-1. **Fix Order**: Address issues in priority order (Critical → High → Medium → Low)
-2. **Fix Process**: For each issue:
-   - Reproduce issue locally
-   - Identify root cause
-   - Implement fix (follow `workflows/implement.md`)
-   - Write test (follow `workflows/test.md`)
-   - Verify fix in browser
-   - Deploy fix
-   - Re-validate in production
-3. **Validation After Each Fix**: Test the specific fix, verify no regressions, check related functionality
-
-## Phase 4: Comprehensive Validation
-
-### 4.1 Complete Use Case Validation
-- Go through each use case systematically
-- Test complete user journeys
-- Verify all steps work correctly
-- Document any remaining issues
-
-### 4.2 Cross-Browser Testing
-- Test in Chrome
-- Test in Firefox
-- Test in Safari (if on Mac)
-- Test in Edge
-- Document browser-specific issues
-
-### 4.3 Responsive Design Testing
-- Test on desktop (1920x1080)
-- Test on tablet (768x1024)
-- Test on mobile (375x667)
-- Verify layouts adapt correctly
-
-### 4.4 Performance Testing
-- Check page load times
-- Test with slow network (throttle)
-- Verify API response times
-- Check for memory leaks
-
-## Phase 5: Production Readiness
-
-### 5.1 Final Checklist
-- [ ] All critical use cases work
-- [ ] No blocking bugs
-- [ ] UI/UX is acceptable
-- [ ] Data persists correctly
-- [ ] Authentication works (if applicable)
-- [ ] Error handling works
-- [ ] Performance is acceptable
-- [ ] Works in major browsers
-- [ ] Responsive design works
-- [ ] Security is implemented
-
-### 5.2 Production Readiness Criteria
-- All high-priority use cases validated
-- No critical bugs remaining
-- Application is stable
-- Performance is acceptable
-- User experience is good
-
-### 5.3 Documentation
-- Document known issues (if any)
-- Create user guide (if needed)
-- Document deployment process
-- Create runbook for common issues
-
-## Validation Patterns
-
-### Use Case Validation Pattern
-```
-1. Navigate to starting page
-2. Perform each step in use case
-3. Verify expected outcomes
-4. Check data persistence
-5. Verify error handling
-6. Test edge cases
-```
-
-### Issue Fix Pattern
-```
-1. Reproduce → 2. Fix (follow workflows/implement.md) → 3. Test (follow workflows/test.md) → 4. Deploy → 5. Validate
-```
-
-## Best Practices
-
-1. **Be Systematic**: Don't skip steps, test everything
-2. **Document Everything**: Record all findings
-3. **Fix Immediately**: Don't accumulate issues (follow `workflows/quality-assurance/iterative-improvement-cycle.md`)
-4. **Test After Fixes**: Always verify fixes work
-5. **Iterate Quickly**: Short fix-validate cycles
-
-## Common Issues & Solutions
-
-1. **Styling Issues**: CSS not loading
-   - **Solution**: Check build process, verify CSS files in dist
-
-2. **API Errors**: 500 errors from API
-   - **Solution**: Check server logs, verify environment variables
-
-3. **Data Not Showing**: Empty lists, missing data
-   - **Solution**: Check database connection, verify seed/test data
-
-4. **Navigation Issues**: Links not working
-   - **Solution**: Check routing configuration, verify paths
-
-5. **Authentication Issues**: Can't login
-   - **Solution**: Check auth implementation, verify session handling
-
-## Output Artifacts
-
-1. **Validation Report**
-   - Use case validation status
-   - Issues found and fixed
-   - Remaining issues (if any)
-
-2. **Issue Log**
-   - All issues documented
-   - Fixes applied
-   - Status of each issue
-
-3. **Production Readiness Report**
-   - Checklist completion
-   - Known issues
-   - Recommendations
-
-## Related Workflows
-- `workflows/quality-assurance/iterative-improvement-cycle.md` - **Recommended**: Systematic review-critique-fix-validate cycle
-- `workflows/implement.md` - For implementing fixes
-- `workflows/test.md` - For writing tests
-- `workflows/deploy/cloud-deployment.md` - For deployment validation