From dcf7146cb17a79aa27fb22fea992d01302d96b55 Mon Sep 17 00:00:00 2001
From: Lucas C <lucas_challamel@yahoo.com>
Date: Sun, 20 Jul 2025 18:25:07 +0200
Subject: [PATCH] feat: Add comprehensive commit and PR workflows as generic
 tasks

- Created create-comprehensive-commit.md task with anti-tunnel vision mechanisms
  - Multi-stream aware commit message generation
  - Systematic evidence gathering from multiple sources
  - Comprehensive context analysis and rationale documentation
  - Quality checklist to prevent tunnel vision

- Created create-comprehensive-pr.md task for detailed PR descriptions
  - Work stream identification and documentation
  - Per-stream testing instructions
  - Visual evidence requirements
  - Review focus areas and deployment notes

- Integrated workflows into dev and architect agents
  - Added *comprehensive-commit command
  - Added *comprehensive-pr command
  - Made workflows available to agents who create commits/PRs

These workflows ensure high-quality git documentation with comprehensive
coverage of all changes, preventing the tunnel vision that often results
in incomplete commit messages or PR descriptions.
---
 bmad-core/agents/architect.md                 |   4 +
 bmad-core/agents/dev.md                       |   4 +
 .../tasks/create-comprehensive-commit.md      | 231 +++++++++++++
 bmad-core/tasks/create-comprehensive-pr.md    | 309 ++++++++++++++++++
 4 files changed, 548 insertions(+)
 create mode 100644 bmad-core/tasks/create-comprehensive-commit.md
 create mode 100644 bmad-core/tasks/create-comprehensive-pr.md

diff --git a/bmad-core/agents/architect.md b/bmad-core/agents/architect.md
index dc33db84..507c2335 100644
--- a/bmad-core/agents/architect.md
+++ b/bmad-core/agents/architect.md
@@ -74,6 +74,8 @@ commands:
   - execute-checklist {checklist}: Run task execute-checklist (default->architect-checklist)
   - research {topic}: execute task create-deep-research-prompt
   - shard-prd: run the task shard-doc.md for the provided architecture.md (ask if not found)
+  - comprehensive-commit: Execute task create-comprehensive-commit for high-quality commit messages
+  - comprehensive-pr: Execute task create-comprehensive-pr for detailed pull request descriptions
   - yolo: Toggle Yolo Mode
   - exit: Say goodbye as the Architect, and then abandon inhabiting this persona
 dependencies:
@@ -83,6 +85,8 @@ dependencies:
     - document-project.md
     - execute-checklist.md
     - create-adr.md
+    - create-comprehensive-commit.md
+    - create-comprehensive-pr.md
   templates:
     - architecture-tmpl.yaml
     - front-end-architecture-tmpl.yaml
diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md
index 4b6dd6aa..293d367e 100644
--- a/bmad-core/agents/dev.md
+++ b/bmad-core/agents/dev.md
@@ -66,6 +66,8 @@ commands:
   - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer.
   - create-dev-journal: Create a development journal entry documenting the session's work
   - list-dev-journals: Show recent dev journal entries from docs/devJournal
+  - comprehensive-commit: Execute task create-comprehensive-commit for high-quality commit messages
+  - comprehensive-pr: Execute task create-comprehensive-pr for detailed pull request descriptions
   - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 develop-story:
   order-of-execution: "Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete"
@@ -82,6 +84,8 @@ dependencies:
     - execute-checklist.md
     - validate-next-story.md
     - create-dev-journal.md
+    - create-comprehensive-commit.md
+    - create-comprehensive-pr.md
   checklists:
     - story-dod-checklist.md
   templates:
diff --git a/bmad-core/tasks/create-comprehensive-commit.md b/bmad-core/tasks/create-comprehensive-commit.md
new file mode 100644
index 00000000..11dbc3c4
--- /dev/null
+++ b/bmad-core/tasks/create-comprehensive-commit.md
@@ -0,0 +1,231 @@
+# Create Comprehensive Commit
+
+This task guides the creation of a high-quality, comprehensive commit message that accurately reflects all staged changes, adhering to Conventional Commits 1.0 standard with anti-tunnel vision mechanisms.
+
+## Purpose
+
+Create commit messages that:
+- Capture ALL work streams, not just the primary change
+- Provide context for future developers
+- Follow Conventional Commits standard
+- Document the "why" behind changes
+- Prevent tunnel vision through systematic evidence gathering
+
+## Process
+
+### 1. Comprehensive Evidence Gathering (MANDATORY)
+
+#### 1.1 Staged Changes Analysis
+Execute and analyze:
+```bash
+# Get summary and detailed view
+git diff --staged --stat
+
+# See operation types (Modified, Added, Deleted)
+git diff --staged --name-status
+```
+
+Group changes by functional area:
+- **Source Code**: Core application logic
+- **API/Backend**: Endpoints, services, repositories
+- **UI/Frontend**: Components, styles, templates
+- **Documentation**: README, docs/, *.md files
+- **Tests**: Test files, test utilities
+- **Configuration**: Config files, environment settings
+- **Database**: Migrations, schema changes
+- **Build/Deploy**: CI/CD, build scripts
+
+For each file, identify:
+- New functionality added
+- Existing functionality modified
+- Bug fixes
+- Refactoring or cleanup
+- Documentation updates
+- Test additions/modifications
+
+#### 1.2 Completeness Check
+```bash
+# Check for unstaged/untracked files
+git status --porcelain
+```
+
+If related files are unstaged:
+- Prompt user about inclusion
+- Ensure completeness of the commit
+
+#### 1.3 Work Stream Identification
+Identify:
+- **Primary Work Stream**: Main focus of the commit
+- **Secondary Work Streams**: Supporting changes
+- **Cross-Functional Impact**: Changes spanning multiple areas
+- **Architecture Impact**: Pattern or structural changes
+
+### 2. Multi-Context Analysis (MANDATORY)
+
+#### 2.1 Session Context
+Review:
+- Conversation history for context
+- Original problem/request
+- Key decisions made
+- Scope evolution (if any)
+
+#### 2.2 Development Context
+Check for:
+- Related dev journal entries
+- Part of larger feature/fix
+- Recent related commits
+- Project milestones
+
+#### 2.3 Business & Technical Context
+Understand:
+- User-facing benefits
+- Technical improvements
+- Problem-solution mapping
+- Alternatives considered
+
+### 3. Commit Message Synthesis
+
+#### 3.1 Type and Scope Selection
+
+**Types** (choose most significant):
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, no logic change
+- `refactor`: Code restructuring
+- `perf`: Performance improvement
+- `test`: Test additions/modifications
+- `chore`: Maintenance tasks
+
+**Scope** examples:
+- Component-specific: `api`, `ui`, `auth`, `db`
+- Feature-specific: `user-management`, `reporting`
+- System-wide: Use when changes affect multiple areas
+
+#### 3.2 Message Structure
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Subject** (≤50 chars):
+- Imperative mood ("add" not "adds")
+- No period at end
+- Capture overall achievement
+
+**Body** (wrap at 72 chars):
+- Explain what and why, not how
+- Break down by work stream if multiple
+- Include context for future developers
+- Technical decisions and rationale
+
+**Footer**:
+- Breaking changes: `BREAKING CHANGE: description`
+- Issue references: `Closes #123`
+- Co-authorship: `Co-Authored-By: Name <email>`
+
+### 4. Anti-Tunnel Vision Checklist
+
+Before finalizing, verify ALL items:
+
+**Content Coverage**:
+- [ ] All staged files explained
+- [ ] All functional areas documented
+- [ ] All work streams identified
+- [ ] Cross-functional impacts noted
+
+**Technical Completeness**:
+- [ ] Code changes include rationale
+- [ ] API changes summarized
+- [ ] UI changes explain user impact
+- [ ] Database changes include migrations
+- [ ] Configuration changes noted
+- [ ] Test changes explained
+
+**Context & Rationale**:
+- [ ] Original problem stated
+- [ ] Solution approach justified
+- [ ] Technical decisions explained
+- [ ] Future implications considered
+
+**Message Quality**:
+- [ ] Subject ≤50 chars, imperative
+- [ ] Body explains what and why
+- [ ] Logical information flow
+- [ ] Appropriate detail level
+- [ ] Conventional Commits format
+
+### 5. Example Multi-Stream Commit
+
+```
+feat(user-management): Add role-based access control with UI and API support
+
+Implemented comprehensive RBAC system to address security audit findings
+and enable fine-grained permission management requested by enterprise
+customers.
+
+API Changes:
+- Added /api/roles endpoints for CRUD operations
+- Extended /api/users with role assignment capabilities
+- Implemented permission checking middleware
+- Added role-based route guards
+
+UI Changes:
+- Created RoleManager component for admin interface
+- Added role assignment UI to user edit form
+- Implemented permission-based UI element visibility
+- Added role badge display to user lists
+
+Database Changes:
+- Added roles and user_roles tables
+- Created permissions lookup table
+- Migrated existing admin users to new role system
+
+Testing:
+- Comprehensive unit tests for role service
+- Integration tests for permission middleware
+- E2E tests for role management workflows
+- Added test fixtures for various permission scenarios
+
+Configuration:
+- Added RBAC feature flags for gradual rollout
+- Extended auth configuration with role providers
+- Added default role mappings
+
+Technical Decisions:
+- Chose RBAC over ABAC for simplicity and performance
+- Implemented as middleware for reusability
+- Used capability-based permissions for flexibility
+
+This enables customers to define custom roles with specific permissions,
+addressing the #1 feature request from enterprise users while maintaining
+backward compatibility with the existing admin/user model.
+
+Closes #234, #245
+Relates to #189
+
+Co-Authored-By: AI Assistant <ai@example.com>
+```
+
+### 6. Execution
+
+After verification:
+1. Present commit message to user
+2. Upon confirmation, execute:
+   ```bash
+   git commit -m "message"
+   # or for multi-line:
+   git commit
+   ```
+
+## Key Principles
+
+- **Prevent Tunnel Vision**: Systematic evidence gathering
+- **Multi-Stream Awareness**: Capture all work, not just primary
+- **Future Developer Focus**: Context over implementation details
+- **Comprehensive Coverage**: No significant work left undocumented
+- **Quality Standards**: Clear, complete, conventional
\ No newline at end of file
diff --git a/bmad-core/tasks/create-comprehensive-pr.md b/bmad-core/tasks/create-comprehensive-pr.md
new file mode 100644
index 00000000..43807713
--- /dev/null
+++ b/bmad-core/tasks/create-comprehensive-pr.md
@@ -0,0 +1,309 @@
+# Create Comprehensive Pull Request
+
+This task guides the creation of a high-quality, comprehensive Pull Request description that helps reviewers understand all changes and speeds up the review process.
+
+## Purpose
+
+Create PR descriptions that:
+- Document ALL work streams comprehensively
+- Provide clear testing instructions
+- Help reviewers focus on important areas
+- Prevent tunnel vision through systematic analysis
+- Make code review efficient and thorough
+
+## Process
+
+### 1. Comprehensive Scope Analysis (MANDATORY)
+
+#### 1.1 Branch and Commit Analysis
+
+Determine base branch and analyze all changes:
+```bash
+# Identify target branch (e.g., main, develop)
+git branch --show-current
+
+# Full commit analysis with details
+git log <base_branch>..HEAD --stat --oneline
+
+# Timeline of development
+git log <base_branch>..HEAD --format="%h %ad %s" --date=short
+```
+
+Group commits by type:
+- Features (feat)
+- Bug fixes (fix)
+- Documentation (docs)
+- Refactoring (refactor)
+- Tests (test)
+- Maintenance (chore)
+
+#### 1.2 File System Impact Analysis
+
+```bash
+# All file changes overview
+git diff <base_branch>..HEAD --name-status
+
+# Detailed diff statistics
+git diff <base_branch>..HEAD --stat
+```
+
+Map changes to functional areas:
+- **API/Backend**: Services, endpoints, business logic
+- **UI/Frontend**: Components, styles, user interfaces
+- **Documentation**: All *.md files, API docs, guides
+- **Tests**: Unit tests, integration tests, E2E tests
+- **Configuration**: Environment configs, build settings
+- **Database**: Migrations, schema changes
+- **Infrastructure**: CI/CD, deployment configs
+
+#### 1.3 Work Stream Identification
+
+Identify distinct work streams:
+- **Primary**: Main feature or fix
+- **Secondary**: Supporting changes
+- **Cross-cutting**: Changes affecting multiple areas
+- **Dependencies**: How streams relate to each other
+
+### 2. Multi-Stream Narrative Synthesis
+
+#### 2.1 Context and Motivation
+
+For each work stream, establish:
+- Problem being solved
+- Current state vs. desired state
+- Business/technical benefits
+- Related issues or tickets
+
+#### 2.2 Technical Implementation
+
+Document for each work stream:
+- Overall approach
+- Architectural decisions
+- Design patterns used
+- Alternative solutions considered
+- Technical trade-offs made
+
+#### 2.3 Integration Points
+
+Identify:
+- How work streams integrate
+- Breaking changes (if any)
+- Backward compatibility measures
+- Future extensibility
+
+### 3. Review Instructions (Per Work Stream)
+
+#### 3.1 Testing Instructions
+
+**API Testing**:
+- Endpoint URLs and methods
+- Sample requests (curl/Postman)
+- Expected responses
+- Error scenarios
+- Authentication requirements
+
+**UI Testing**:
+- User flows step-by-step
+- Screenshots/GIFs (before/after)
+- Browser compatibility notes
+- Responsive design checks
+- Accessibility verification
+
+**Database Testing**:
+- Migration commands
+- Verification queries
+- Rollback procedures
+- Data integrity checks
+
+**Configuration Testing**:
+- Environment setup steps
+- New variables/settings
+- Deployment considerations
+
+#### 3.2 Review Focus Areas
+
+Highlight:
+- Complex logic needing attention
+- Security-sensitive changes
+- Performance-critical code
+- Breaking changes
+- New patterns introduced
+
+### 4. PR Description Template
+
+```markdown
+## Summary
+
+[2-3 sentences explaining the PR's purpose and main achievement]
+
+## Context
+
+**Problem**: [What issue does this solve?]
+**Solution**: [High-level approach taken]
+**Impact**: [Who benefits and how?]
+
+## Work Streams
+
+### 🎯 Primary: [Main Feature/Fix Name]
+- **What**: [Brief description]
+- **Files**: [Key files changed]
+- **Impact**: [User/system impact]
+
+### 🔧 Secondary: [Supporting Changes]
+- **What**: [Brief description]
+- **Files**: [Key files changed]
+- **Reason**: [Why needed]
+
+## Technical Changes
+
+### API Changes
+- **New Endpoints**:
+  - `POST /api/v1/resource` - Creates new resource
+  - `GET /api/v1/resource/:id` - Retrieves resource
+- **Modified Endpoints**:
+  - `PUT /api/v1/existing` - Added field validation
+- **Breaking Changes**: None
+
+### UI Changes
+- **New Components**:
+  - `ResourceManager` - Main management interface
+  - `ResourceForm` - Creation/edit form
+- **Updated Components**:
+  - `Dashboard` - Added resource widget
+- **User Experience**:
+  - Simplified workflow for resource creation
+  - Added inline validation feedback
+
+### Database Changes
+- **Migrations**:
+  - `001_add_resources_table.sql` - New resource storage
+  - `002_add_resource_indexes.sql` - Performance indexes
+- **Model Changes**:
+  - Added Resource entity with relations
+
+### Tests Added
+- **Unit Tests**: 15 new tests for resource service
+- **Integration Tests**: API endpoint coverage
+- **E2E Tests**: Full user workflow validation
+
+## Testing Instructions
+
+### API Testing
+
+1. Create a new resource:
+   ```bash
+   curl -X POST http://localhost:8080/api/v1/resource \
+     -H "Content-Type: application/json" \
+     -d '{"name": "Test Resource", "type": "example"}'
+   ```
+   Expected: 201 Created with resource ID
+
+2. Retrieve the resource:
+   ```bash
+   curl http://localhost:8080/api/v1/resource/{id}
+   ```
+   Expected: 200 OK with resource data
+
+### UI Testing
+
+1. Navigate to Dashboard
+2. Click "Add Resource" button
+3. Fill form with test data
+4. Submit and verify success message
+5. Check resource appears in list
+
+### Database Verification
+
+```sql
+-- Verify migration success
+SELECT * FROM schema_version ORDER BY installed_on DESC LIMIT 2;
+
+-- Check data integrity
+SELECT COUNT(*) FROM resources;
+```
+
+## Screenshots
+
+### Before
+[Dashboard without resource management]
+
+### After
+[Dashboard with new resource section]
+[Resource creation form]
+[Success state]
+
+## Review Checklist
+
+### For Reviewers
+- [ ] API contracts match documentation
+- [ ] Error handling is comprehensive
+- [ ] UI follows design system
+- [ ] Tests provide adequate coverage
+- [ ] Performance impact is acceptable
+- [ ] Security best practices followed
+
+### Pre-Merge Checklist
+- [ ] All CI checks passing
+- [ ] Documentation updated
+- [ ] CHANGELOG entry added
+- [ ] No console.log or debug code
+- [ ] Breaking changes communicated
+
+## Deployment Notes
+
+- **Database**: Run migrations before deploying code
+- **Config**: Add `RESOURCE_FEATURE_FLAG=true` to enable
+- **Rollback**: Feature flag can disable without code rollback
+
+## Related Issues
+
+Closes #123 - Add resource management
+Relates to #100 - Overall admin improvements
+
+---
+
+**Questions for Reviewers**:
+1. Should we add pagination to the resource list immediately?
+2. Any concerns about the permission model?
+```
+
+### 5. Anti-Tunnel Vision Checklist
+
+Verify before finalizing:
+
+**Content Coverage**:
+- [ ] All commits explained
+- [ ] All files accounted for
+- [ ] All work streams documented
+- [ ] Cross-functional impacts noted
+
+**Technical Completeness**:
+- [ ] API changes detailed with examples
+- [ ] UI changes shown visually
+- [ ] Database changes include migrations
+- [ ] Config changes documented
+- [ ] Tests described
+
+**Review Readiness**:
+- [ ] Testing steps are reproducible
+- [ ] Focus areas highlighted
+- [ ] Deployment notes included
+- [ ] Breaking changes clear
+- [ ] Questions for reviewers listed
+
+### 6. Execution
+
+1. Generate PR description using template
+2. Include all evidence gathered
+3. Add screenshots/recordings
+4. Review completeness
+5. Present to user for approval
+6. User creates PR on platform
+
+## Key Principles
+
+- **Comprehensive Coverage**: Document all changes, not just primary
+- **Reviewer Empathy**: Make review process efficient
+- **Visual Evidence**: Screenshots/GIFs for UI changes
+- **Reproducible Testing**: Clear, step-by-step instructions
+- **Future Reference**: Context for why decisions were made
\ No newline at end of file