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.
This commit is contained in:
Lucas C
parent
44e14f26ed
commit
dcf7146cb1
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue