fraim-framework 2.0.30 → 2.0.33

package/registry/workflows/replicate/replicate-to-issues.md

@@ -0,0 +1,319 @@
+# Replicate to Issues Workflow
+
+## INTENT
+To convert comprehensive replication analysis into actionable GitHub issues that can be implemented through standard FRAIM workflows (spec → design → implement → test).
+
+## PRINCIPLES
+- **One Issue Per Feature**: Each use case becomes a focused, implementable issue
+- **Complete Context**: Include all relevant screenshots, requirements, and technical notes
+- **Proper Prioritization**: Use priority from discovery analysis
+- **Clear Acceptance Criteria**: Make issues testable and verifiable
+- **Linked Dependencies**: Connect related issues appropriately
+
+## Overview
+This workflow guides agents through converting the outputs from `replicate-discovery.md` into well-structured GitHub issues. Each issue represents a feature or use case that can be implemented through the standard FRAIM spec/design/implement/test workflow.
+
+## Prerequisites
+- Completed Replicate Discovery workflow (`workflows/replicate/replicate-discovery.md`)
+- Access to `docs/replicate/` directory with all analysis artifacts
+- GitHub repository access with issue creation permissions
+- Understanding of the target implementation repository
+
+## Workflow Steps
+
+### Phase 1: Prepare Issue Generation
+
+1. **Review Discovery Artifacts**
+   - Read `docs/replicate/REPLICATION_ANALYSIS.md`
+   - Review `docs/replicate/reports/use-cases.md`
+   - Check `docs/replicate/reports/technology-stack.md`
+   - Verify all screenshots are accessible
+
+2. **Define Issue Structure**
+   Each issue should include:
+   - **Title**: Clear, concise feature name
+   - **Description**: What needs to be built
+   - **User Story**: As a [role], I want [feature] so that [benefit]
+   - **Use Case Reference**: Link to use case in discovery docs
+   - **Screenshots**: Embedded or linked screenshots
+   - **Technical Requirements**: Technology, components, APIs needed
+   - **Acceptance Criteria**: Testable conditions for completion
+   - **Priority**: High/Medium/Low from discovery
+   - **Labels**: Feature type, priority, component area
+   - **Dependencies**: Links to related issues
+
+3. **Create Issue Template**
+   ```markdown
+   ## User Story
+   As a [role], I want [feature] so that [benefit].
+   
+   ## Description
+   [Detailed description of the feature]
+   
+   ## Use Case Reference
+   See: `docs/replicate/reports/use-cases.md` - UC-[number]
+   
+   ## Screenshots
+   ![Screenshot](<path-to-screenshot>)
+   
+   ## Technical Requirements
+   - **Components**: [List of UI components needed]
+   - **Data Models**: [Entities and fields]
+   - **API Endpoints**: [Required endpoints]
+   - **Dependencies**: [External libraries or services]
+   
+   ## Acceptance Criteria
+   - [ ] [Testable criterion 1]
+   - [ ] [Testable criterion 2]
+   - [ ] [Testable criterion 3]
+   
+   ## Implementation Notes
+   [Any additional technical notes or considerations]
+   
+   ## Related Issues
+   - Depends on: #[issue-number]
+   - Related to: #[issue-number]
+   ```
+
+### Phase 2: Categorize and Prioritize
+
+1. **Group Use Cases by Implementation Order**
+   Typical order:
+   1. **Foundation** (Priority: High)
+      - Project setup and configuration
+      - Database schema and models
+      - Authentication system
+      - Basic routing and navigation
+   
+   2. **Core Features** (Priority: High)
+      - Primary user workflows
+      - Essential CRUD operations
+      - Main user interfaces
+   
+   3. **Secondary Features** (Priority: Medium)
+      - Supporting functionality
+      - Additional user workflows
+      - Enhanced features
+   
+   4. **Polish & Enhancement** (Priority: Low)
+      - UI/UX improvements
+      - Edge cases
+      - Nice-to-have features
+
+2. **Identify Dependencies**
+   - Authentication must come before protected features
+   - Data models before features that use them
+   - Shared components before pages that use them
+   - API endpoints before frontend features
+
+3. **Create Implementation Roadmap**
+   Document in `docs/replicate/IMPLEMENTATION_ROADMAP.md`:
+   - Phase 1: Foundation (issues #1-10)
+   - Phase 2: Core Features (issues #11-30)
+   - Phase 3: Secondary Features (issues #31-50)
+   - Phase 4: Polish (issues #51+)
+
+### Phase 3: Generate GitHub Issues
+
+1. **Create Foundation Issues**
+   Generate issues for:
+   - Project setup and tooling
+   - Database schema design
+   - Authentication system
+   - Base layout and navigation
+   - Shared component library
+
+2. **Create Feature Issues**
+   For each use case in `docs/replicate/reports/use-cases.md`:
+   - Extract use case details
+   - Format as GitHub issue
+   - Include relevant screenshots
+   - Add technical requirements
+   - Set priority and labels
+   - Note dependencies
+
+3. **Use GitHub API or CLI**
+   ```bash
+   # Using GitHub CLI
+   gh issue create \
+     --title "Implement User Registration" \
+     --body-file issue-template.md \
+     --label "feature,high-priority,authentication" \
+     --assignee @me
+   ```
+
+4. **Batch Issue Creation**
+   Create a script or use MCP GitHub tools:
+   - Read use cases from `docs/replicate/reports/use-cases.md`
+   - Generate issue body for each
+   - Create issues via API
+   - Track created issue numbers
+   - Update dependency links
+
+### Phase 4: Link and Organize
+
+1. **Update Issue Dependencies**
+   - After all issues created, update with dependency links
+   - Use "Depends on #X" or "Blocked by #X"
+   - Link related issues with "Related to #X"
+
+2. **Create GitHub Milestones**
+   - Foundation Milestone
+   - Core Features Milestone
+   - Secondary Features Milestone
+   - Polish & Launch Milestone
+
+3. **Assign Issues to Milestones**
+   - Group issues by implementation phase
+   - Set milestone due dates if applicable
+
+4. **Create Project Board** (Optional)
+   - Columns: Backlog, Spec, Design, Implementation, Testing, Done
+   - Add all issues to board
+   - Organize by priority and dependencies
+
+### Phase 5: Documentation
+
+1. **Create Issue Index**
+   Generate `docs/replicate/GITHUB_ISSUES.md`:
+   ```markdown
+   # GitHub Issues Index
+   
+   ## Foundation Issues
+   - #1: Project Setup and Configuration
+   - #2: Database Schema Design
+   - #3: Authentication System
+   
+   ## Core Features
+   - #10: User Registration
+   - #11: User Login
+   - #12: Event Listing
+   
+   [etc.]
+   ```
+
+2. **Update Master Report**
+   Add to `docs/replicate/REPLICATION_ANALYSIS.md`:
+   - Link to GitHub issues
+   - Implementation roadmap
+   - Next steps for development
+
+3. **Create Developer Guide**
+   Generate `docs/replicate/DEVELOPER_GUIDE.md`:
+   - How to pick up an issue
+   - Workflow: spec → design → implement → test
+   - Where to find reference materials
+   - How to use discovery artifacts
+
+## Output Artifacts
+
+After completing this workflow, you should have:
+
+1. **GitHub Issues**
+   - One issue per feature/use case
+   - Properly labeled and prioritized
+   - With dependencies linked
+   - Assigned to milestones
+
+2. **Documentation**
+   - `docs/replicate/IMPLEMENTATION_ROADMAP.md` - Phased implementation plan
+   - `docs/replicate/GITHUB_ISSUES.md` - Index of all created issues
+   - `docs/replicate/DEVELOPER_GUIDE.md` - How to work with issues
+
+3. **Project Organization**
+   - GitHub milestones created
+   - Project board set up (optional)
+   - Issues organized and ready for work
+
+## Issue Labeling Strategy
+
+Use consistent labels:
+- **Type**: `feature`, `bug`, `enhancement`, `documentation`
+- **Priority**: `high-priority`, `medium-priority`, `low-priority`
+- **Component**: `authentication`, `ui`, `api`, `database`, `navigation`
+- **Status**: `needs-spec`, `needs-design`, `ready-for-implementation`, `blocked`
+- **Phase**: `foundation`, `core`, `secondary`, `polish`
+
+## Best Practices
+
+1. **Keep Issues Focused**: One feature per issue, not too broad
+2. **Include Context**: Link to discovery docs and screenshots
+3. **Clear Acceptance Criteria**: Make it obvious when done
+4. **Realistic Scope**: Issues should be completable in reasonable time
+5. **Update Dependencies**: Keep dependency links current
+6. **Use Templates**: Consistent issue format helps clarity
+
+## Common Patterns
+
+### Foundation Issue Example
+```markdown
+Title: Set Up Database Schema for User Management
+
+## User Story
+As a developer, I want a well-designed database schema so that I can implement user-related features.
+
+## Description
+Design and implement the database schema for user management based on the discovery analysis.
+
+## Technical Requirements
+- User table with fields: id, email, password_hash, name, created_at, updated_at
+- Profile table with additional user information
+- Proper indexes and constraints
+- Migration scripts
+
+## Acceptance Criteria
+- [ ] Database schema designed and documented
+- [ ] Migration scripts created
+- [ ] Schema matches requirements from discovery
+- [ ] Indexes added for performance
+- [ ] Foreign keys and constraints properly set
+
+## Related Issues
+- Blocks: #10 (User Registration)
+- Blocks: #11 (User Login)
+```
+
+### Feature Issue Example
+```markdown
+Title: Implement Event Listing Page
+
+## User Story
+As a user, I want to see a list of upcoming events so that I can find events to attend.
+
+## Description
+Implement the event listing page showing all upcoming events with filtering and search capabilities.
+
+## Use Case Reference
+See: `docs/replicate/reports/use-cases.md` - UC-15
+
+## Screenshots
+![Event List](docs/replicate/screenshots/events/event-list.png)
+
+## Technical Requirements
+- **Components**: EventCard, EventList, FilterBar, SearchBox
+- **Data Models**: Event (id, title, date, location, description)
+- **API Endpoints**: GET /api/events?filter=upcoming&search=query
+- **Dependencies**: React, date-fns for date formatting
+
+## Acceptance Criteria
+- [ ] Event list displays all upcoming events
+- [ ] Events can be filtered by date, location, category
+- [ ] Search functionality works
+- [ ] Pagination implemented (20 events per page)
+- [ ] Responsive design matches screenshots
+- [ ] Loading and error states handled
+
+## Implementation Notes
+- Use infinite scroll or pagination
+- Cache event data for performance
+- Consider using React Query for data fetching
+
+## Related Issues
+- Depends on: #5 (Event Data Model)
+- Depends on: #8 (Event API Endpoints)
+- Related to: #16 (Event Detail Page)
+```
+
+## Next Steps
+
+After completing this workflow, let the user verify and once in agreement, recommend that the product-building workflows be started with prep-issue, spec, design, implement phases