BMAD-METHOD/tmp/workflows/pull-request.md

description
A Pull Request documentation workflow

This workflow guides the creation of a high-quality, comprehensive Pull Request description. A great PR description is the fastest way to get your changes reviewed and merged.

1. Comprehensive Scope Analysis (MANDATORY - Prevent tunnel vision):

1.1. Branch and Commit Analysis:

• Determine the Base Branch: Identify the target branch for the merge (e.g., main, develop).
• Full Commit Analysis: Run git log <base_branch>..HEAD --stat --oneline to get both summary and detailed changes for all commits in this PR.
• Commit Categorization: Group commits by type (feat, fix, docs, refactor, test, chore) to understand the full scope.
• Time Range Assessment: Run git log <base_branch>..HEAD --format="%h %ad %s" --date=short to understand the development timeline.

1.2. File System Impact Analysis:

• Changed Files Overview: Run git diff <base_branch>..HEAD --name-status to see all modified, added, and deleted files.
• Functional Area Mapping: Group changed files by functional area:
  • API Changes: src/groovy/umig/api/, src/groovy/umig/repository/
  • UI Changes: src/groovy/umig/web/js/, src/groovy/umig/web/css/, src/groovy/umig/macros/
  • Documentation: docs/, README.md, CHANGELOG.md, *.md files
  • Tests: src/groovy/umig/tests/, local-dev-setup/__tests__/
  • Configuration: local-dev-setup/liquibase/, *.json, *.yml, *.properties
  • Database: Migration files, schema changes
• Cross-Functional Impact: Identify changes that span multiple functional areas.

1.3. Work Stream Identification:

• Primary Work Streams: Based on commits and file changes, identify distinct work streams (e.g., "API implementation", "UI refactoring", "documentation updates").
• Secondary Work Streams: Identify supporting work (e.g., "schema fixes", "test updates", "configuration changes").
• Parallel vs Sequential: Determine which work streams were done in parallel vs. sequence.
• Dependencies: Note how different work streams depend on each other.

2. Multi-Stream Narrative Synthesis (MANDATORY - Address tunnel vision):

A PR is a story that may have multiple parallel themes. You need to explain the "why," the "what," and the "how" for each work stream.

2.1. Context and Motivation Analysis:

• Development Context: Review recent dev journal entries, session context, and any associated tickets (e.g., Jira, GitHub Issues).
• Problem Statement: For each work stream, clearly articulate:
  • What problem was being solved or feature being added?
  • What was the state of the application before this change?
  • What will it be after?
• Business Impact: Explain the user-facing or technical benefits of the changes.
• Scope Evolution: If the PR scope expanded during development, explain how and why.

2.2. Technical Implementation Analysis:

• Architecture Overview: Describe the overall technical approach and any significant architectural decisions.
• Work Stream Details: For each work stream identified in step 1:
  • API Changes: New endpoints, schema modifications, repository patterns
  • UI Changes: Component modifications, styling updates, user experience improvements
  • Documentation: What docs were updated and why
  • Database Changes: Schema migrations, data model updates
  • Configuration: Environment or build configuration changes
  • Tests: New test coverage, test framework updates
• Technical Decisions: Explain why you chose specific solutions over alternatives.
• Patterns and Standards: Note adherence to or establishment of new project patterns.

2.3. Integration and Dependencies:

• Cross-Stream Integration: How different work streams work together.
• Breaking Changes: Any breaking changes and migration path.
• Backward Compatibility: How existing functionality is preserved.
• Future Implications: What this change enables for future development.

3. Comprehensive Review Instructions (MANDATORY - Cover all work streams):

Make it easy for others to review your work across all functional areas.

3.1. Testing Instructions by Work Stream:

• API Testing: For each new or modified API endpoint:
  • Provide curl commands or Postman collection references
  • Include expected request/response examples
  • Note any authentication or setup requirements
  • Identify edge cases and error scenarios to test
• UI Testing: For each UI change:
  • Provide step-by-step user interaction flows
  • Include screenshots or GIFs showing before/after states
  • Identify specific user scenarios to test
  • Note any browser-specific considerations
• Database Testing: For schema changes:
  • Provide migration verification steps
  • Include data verification queries
  • Note any rollback procedures
• Configuration Testing: For environment changes:
  • Provide setup or configuration verification steps
  • Include any new environment variables or settings
  • Note any deployment considerations

3.2. Review Focus Areas:

• Code Quality: Highlight areas that need particular attention (complex logic, new patterns, potential performance impacts).
• Security: Note any security considerations or authentication changes.
• Performance: Identify any performance-critical changes or optimizations.
• Compatibility: Note any backward compatibility concerns or breaking changes.

3.3. Verification Checklist:

• Functional Verification: What specific functionality should reviewers verify works correctly?
• Integration Testing: How should reviewers verify that different components work together?
• Edge Case Testing: What edge cases or error conditions should be tested?
• Documentation Review: What documentation should be reviewed for accuracy and completeness?

4. Enhanced PR Description Template (MANDATORY - Multi-stream aware):

Use a structured template that accommodates multiple work streams and comprehensive coverage.

4.1. Title Construction:

• Primary Work Stream: Use the most significant work stream for the title following Conventional Commits standard.
• Multi-Stream Indicator: If multiple significant work streams exist, use a broader scope (e.g., feat(admin): complete user management system with API and UI).

4.2. Enhanced Body Template:

## Summary

<!-- Brief overview of the PR's purpose and scope. What problem does this solve? -->

## Work Streams

<!-- List all major work streams in this PR -->

### 🚀 [Primary Work Stream Name]

- Brief description of changes
- Key files modified
- Impact on users/system

### 🔧 [Secondary Work Stream Name]

- Brief description of changes
- Key files modified
- Impact on users/system

## Technical Changes

<!-- Detailed breakdown by functional area -->

### API Changes

- New endpoints:
- Modified endpoints:
- Schema changes:
- Repository updates:

### UI Changes

- New components:
- Modified components:
- Styling updates:
- User experience improvements:

### Database Changes

- Schema migrations:
- Data model updates:
- Migration scripts:

### Documentation Updates

- API documentation:
- User documentation:
- Developer documentation:
- Configuration documentation:

## Testing Instructions

<!-- Work stream specific testing -->

### API Testing

1. [Specific API test steps]
2. [Expected outcomes]
3. [Edge cases to verify]

### UI Testing

1. [Specific UI test steps]
2. [User flows to verify]
3. [Browser compatibility checks]

### Database Testing

1. [Migration verification]
2. [Data integrity checks]
3. [Rollback verification]

## Screenshots / Recordings

<!-- Visual evidence of changes -->

### Before

[Screenshots/GIFs of old behavior]

### After

[Screenshots/GIFs of new behavior]

## Review Focus Areas

<!-- Areas needing particular attention -->

- [ ] **Code Quality:** [Specific areas to focus on]
- [ ] **Security:** [Security considerations]
- [ ] **Performance:** [Performance impacts]
- [ ] **Compatibility:** [Breaking changes or compatibility concerns]

## Deployment Notes

<!-- Any special deployment considerations -->

- Environment variables:
- Configuration changes:
- Database migrations:
- Rollback procedures:

## Related Issues

<!-- Link to any related issues, e.g., "Closes #123" -->

## Checklist

- [ ] All work streams are documented above
- [ ] Testing instructions cover all functional areas
- [ ] Documentation is updated for all changes
- [ ] Database migrations are tested
- [ ] API changes are documented
- [ ] UI changes are demonstrated with screenshots
- [ ] Code follows project style guidelines
- [ ] All tests pass
- [ ] Breaking changes are documented
- [ ] Deployment considerations are noted

5. Anti-Tunnel Vision Verification (MANDATORY - Use before finalizing):

Before presenting the PR description, verify you have addressed ALL of the following:

Content Coverage:

• All commits in the PR are explained
• All modified files are accounted for
• All functional areas touched are documented
• All work streams are identified and described
• Cross-functional impacts are noted

Technical Completeness:

• API changes include endpoint details and examples
• UI changes include visual evidence and user flows
• Database changes include migration details
• Configuration changes include deployment notes
• Documentation updates are comprehensive

Review Readiness:

• Testing instructions are clear and complete
• Review focus areas are identified
• Deployment considerations are documented
• Rollback procedures are noted (if applicable)
• Breaking changes are clearly highlighted

6. Final Review:

• Present the generated PR title and body to the user for final review and approval before they create the pull request on their Git platform.