Comprehensive knowledge for creating, managing, and merging pull requests with Jira integration, following best practices for code review, deployment, and team collaboration
This skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides comprehensive guidance for creating, managing, and merging pull requests with Jira integration, following industry best practices for code review, deployment safety, and team collaboration.
<type>/<jira-key>-<short-description>
| Type | Purpose | Example |
|---|---|---|
feature | New features | feature/PROJ-123-user-authentication |
bugfix | Bug fixes | bugfix/PROJ-456-login-error |
hotfix | Urgent production fixes | hotfix/PROJ-789-payment-failure |
refactor | Code refactoring | refactor/PROJ-234-database-queries |
docs | Documentation only | docs/PROJ-567-api-documentation |
test | Adding/updating tests | test/PROJ-890-integration-tests |
chore | Maintenance tasks | chore/PROJ-345-dependency-update |
perf | Performance improvements | perf/PROJ-678-query-optimization |
- and /# Good
feature/LOBBI-1234-member-dashboard
bugfix/LOBBI-5678-email-validation
hotfix/LOBBI-9012-critical-auth-bug
# Bad
feature/add_new_feature
LOBBI-1234
my-branch
fix-bug-in-production
<type>(<scope>): <subject>
<body>
<footer>
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, no logic change)refactor: Code refactoringperf: Performance improvementstest: Adding or updating testschore: Maintenance tasksbuild: Build system changesci: CI/CD changesrevert: Reverting previous commitsBREAKING CHANGE: descriptionCloses PROJ-123Refs PROJ-456, PROJ-789# Simple commit
feat(auth): add OAuth2 login support
# With body
fix(api): resolve race condition in user creation
The user creation endpoint could create duplicate users when
called simultaneously. Added database-level unique constraint
and proper error handling.
Closes LOBBI-5678
# Breaking change
feat(api): update authentication flow
BREAKING CHANGE: Authentication now requires API version header.
Clients must include 'X-API-Version: 2.0' in all requests.
Refs LOBBI-1234
# Multiple changes
refactor(database): optimize query performance
- Add indexes to frequently queried columns
- Use eager loading for related entities
- Implement query result caching
- Remove N+1 query patterns
Performance improved by 60% in testing.
Closes LOBBI-3456
[JIRA-KEY] Type: Brief description
[LOBBI-1234] Feature: Add member dashboard with activity feed
[LOBBI-5678] Fix: Resolve email validation error on signup
[LOBBI-9012] Hotfix: Critical authentication bug in production
[LOBBI-3456] Refactor: Optimize database query performance
[LOBBI-7890] Docs: Update API documentation for v2.0
Use this template for all PRs:
## Summary
[Brief overview of changes - 2-3 sentences]
## Jira Ticket
- **Issue:** [PROJ-123](https://your-jira.atlassian.net/browse/PROJ-123)
- **Type:** Feature | Bug Fix | Hotfix | Refactor | Documentation
- **Priority:** Critical | High | Medium | Low
## Changes Made
- List key changes
- Use bullet points
- Be specific and concise
## Technical Details
### Architecture Changes
- Describe any architectural decisions
- Explain design patterns used
### Database Changes
- Schema migrations
- New tables/columns
- Index additions
### API Changes
- New endpoints
- Modified endpoints
- Breaking changes
## Testing
### Test Coverage
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] E2E tests added/updated
- [ ] Manual testing completed
### Test Instructions
1. Step-by-step instructions for reviewers
2. Include test data or scenarios
3. Expected outcomes
### Test Results
- Coverage: XX%
- All tests passing: Yes/No
- Performance benchmarks: [if applicable]
## Screenshots/Videos
[If UI changes, include before/after screenshots or demo video]
## Deployment Notes
### Risk Assessment
- **Risk Level:** Low | Medium | High | Critical
- **Rollback Plan:** [Describe rollback procedure]
### Prerequisites
- [ ] Database migrations ready
- [ ] Environment variables configured
- [ ] Feature flags set
- [ ] Dependencies updated
### Migration Steps
1. Run migrations: `npm run migrate:up`
2. Deploy application
3. Verify health checks
4. Enable feature flag (if applicable)
### Rollback Procedure
1. Disable feature flag
2. Revert deployment
3. Run down migration: `npm run migrate:down`
## Dependencies
- Related PRs: #123, #456
- Blocked by: #789
- Blocks: #234
## Checklist
- [ ] Code follows project style guide
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No console.log or debug code
- [ ] No commented-out code
- [ ] Environment variables documented
- [ ] CHANGELOG.md updated
- [ ] Breaking changes documented
- [ ] Jira ticket updated
## Additional Notes
[Any other context, concerns, or discussion points]
## Feature Summary
[What feature is being added and why]
## Jira Ticket
- **Issue:** [PROJ-123](https://jira.example.com/browse/PROJ-123)
- **Epic:** [PROJ-100](https://jira.example.com/browse/PROJ-100)
## User Story
As a [user type],
I want [goal],
So that [benefit].
## Implementation Details
### New Components
- Component A: Purpose and functionality
- Component B: Purpose and functionality
### Modified Components
- Component C: What changed and why
### New Dependencies
- package-name@version: Why it's needed
## API Changes
### New Endpoints
POST /api/v1/resource GET /api/v1/resource/:id PUT /api/v1/resource/:id DELETE /api/v1/resource/:id
### Request/Response Examples
```json
// POST /api/v1/resource
{
"name": "Example",
"type": "demo"
}
// Response
{
"id": "123",
"name": "Example",
"type": "demo",
"created_at": "2025-12-17T10:00:00Z"
}
enable_new_featurefalse
### Bugfix PR Template
```markdown
## Bug Description
[What was broken and how it manifested]
## Jira Ticket
- **Issue:** [PROJ-456](https://jira.example.com/browse/PROJ-456)
- **Severity:** Critical | High | Medium | Low
## Root Cause
[Technical explanation of what caused the bug]
## Solution
[How the bug was fixed]
## Code Changes
### Files Modified
- `src/path/to/file.ts`: Fixed [specific issue]
- `tests/path/to/test.ts`: Added regression test
### Before (Problematic Code)
```javascript
// Code that caused the issue
function buggyFunction() {
// problematic logic
}
// Fixed code
function fixedFunction() {
// corrected logic
}
describe('bugfix PROJ-456', () => {
it('should handle edge case correctly', () => {
// Test that prevents regression
});
});
### Hotfix PR Template
```markdown
## HOTFIX - URGENT
## Critical Issue
[Clear description of the production issue]
## Jira Ticket
- **Issue:** [PROJ-789](https://jira.example.com/browse/PROJ-789)
- **Severity:** CRITICAL
- **Incident Report:** [Link to incident]
## Impact
- **Users Affected:** [Estimate]
- **Business Impact:** [Revenue, reputation, compliance]
- **Started:** [Timestamp]
- **Duration:** [How long issue has existed]
## Root Cause
[Quick analysis of what went wrong]
## Immediate Fix
[What this PR does to stop the bleeding]
## Long-term Solution
[Follow-up work needed - create Jira tickets]
## Fast-Track Approval
- [ ] Tested in staging replica
- [ ] Rollback plan ready
- [ ] On-call team notified
- [ ] Monitoring alerts configured
## Deployment
- **Deploy ASAP:** YES
- **Requires Downtime:** Yes/No
- **Rollback Time:** [Estimate]
## Post-Deployment
- [ ] Verify fix in production
- [ ] Monitor for 30 minutes
- [ ] Update incident report
- [ ] Schedule post-mortem
Code Owner (Required)
Subject Matter Expert (Optional)
Team Lead (For Major Changes)
| Label | Purpose | When to Use |
|---|---|---|
needs-review | Awaiting initial review | When PR is ready |
needs-changes | Changes requested | After review feedback |
approved | Ready to merge | All reviews approved |
security-review | Requires security check | Auth, permissions, data handling |
breaking-change | Contains breaking changes | API changes, deprecations |
hotfix | Urgent production fix | Critical issues |
wip | Work in progress | Not ready for review |
size/small | < 100 lines changed | Auto-applied |
size/medium | 100-500 lines | Auto-applied |
size/large | > 500 lines | Auto-applied, consider splitting |
## Code Quality
- [ ] Code is readable and maintainable
- [ ] Follows project style guide
- [ ] No code smells or anti-patterns
- [ ] DRY principle followed
- [ ] SOLID principles applied
## Functionality
- [ ] Changes match PR description
- [ ] Edge cases handled
- [ ] Error handling appropriate
- [ ] Input validation present
- [ ] No hardcoded values
## Testing
- [ ] Tests are comprehensive
- [ ] Tests are readable
- [ ] Coverage is adequate
- [ ] Tests actually test the right things
- [ ] No flaky tests
## Security
- [ ] No sensitive data exposed
- [ ] Authentication/authorization correct
- [ ] Input sanitization present
- [ ] SQL injection prevented
- [ ] XSS prevention in place
## Performance
- [ ] No obvious performance issues
- [ ] Database queries optimized
- [ ] Proper indexing used
- [ ] No N+1 queries
- [ ] Caching considered
## Documentation
- [ ] Code comments where needed
- [ ] API documentation updated
- [ ] README updated if needed
- [ ] CHANGELOG updated
- [ ] Breaking changes documented
Before merging, ensure:
Status Checks Pass
Approvals Met
Branch Up-to-Date
Documentation Complete
When to Use:
Benefits:
Process:
# GitHub will squash automatically, or manually:
git checkout main
git merge --squash feature/PROJ-123-new-feature
git commit -m "feat: add new feature [PROJ-123]"
git push origin main
When to Use:
Benefits:
Process:
git checkout main
git merge --no-ff feature/PROJ-123-new-feature
git push origin main
When to Use:
Benefits:
Process:
git checkout feature/PROJ-123-new-feature
git rebase main
git push --force-with-lease origin feature/PROJ-123-new-feature
# Then merge via GitHub
| Scenario | Strategy | Reason |
|---|---|---|
| Feature with multiple WIP commits | Squash | Clean up history |
| Hotfix (single commit) | Rebase | Keep linear |
| Large feature (team effort) | Merge Commit | Preserve history |
| Bug fix (2-3 commits) | Squash | Simplify |
| Refactoring (many logical steps) | Merge Commit | Show progression |
Include Jira key in:
feature/PROJ-123-description[PROJ-123] Add new featurefeat: add feature (PROJ-123)In PR description:
## Jira Ticket
- **Issue:** [PROJ-123](https://jira.example.com/browse/PROJ-123)
- **Type:** Feature
- **Priority:** High
Closes PROJ-123
PRs should trigger automatic status updates:
| PR Event | Jira Status Transition |
|---|---|
| PR opened | To Do → In Progress |
| PR ready for review | In Progress → In Review |
| Changes requested | In Review → In Progress |
| PR approved | In Review → Ready for Merge |
| PR merged | Ready for Merge → Done |
| PR closed (not merged) | Any → Cancelled |
Automatically post to Jira:
Pull Request opened: [PR #123](https://github.com/org/repo/pull/123)
**Title:** [PROJ-123] Add new feature
**Author:** @developer
**Status:** Ready for Review
**Files Changed:** 15
**Lines Added:** +250, Removed: -100
[View Pull Request](https://github.com/org/repo/pull/123)
## Risk Assessment
### Risk Level: [Low | Medium | High | Critical]
### Risk Factors
- [ ] Database schema changes
- [ ] API breaking changes
- [ ] Third-party integration changes
- [ ] Authentication/authorization changes
- [ ] Performance-critical code modified
- [ ] High-traffic endpoints affected
- [ ] Data migration required
### Impact Analysis
- **User Impact:** [Describe who is affected]
- **System Impact:** [Services/components affected]
- **Data Impact:** [Any data modifications]
- **Downtime Required:** Yes/No - [Duration]
### Mitigation Strategies
1. [Strategy to reduce risk]
2. [Backup plan]
3. [Monitoring approach]
## Rollback Procedure
### Triggers
- Critical bug discovered
- Performance degradation > 20%
- User-reported issues spike
- Health checks failing
### Steps
1. **Immediate Actions** (0-5 minutes)
- Alert on-call team
- Document issue in incident channel
- Prepare rollback command
2. **Execute Rollback** (5-10 minutes)
```bash
# Kubernetes
kubectl rollout undo deployment/app-name -n namespace
# Helm
helm rollback release-name -n namespace
# Vercel
vercel rollback [deployment-url]
Verify Rollback (10-15 minutes)
Database Rollback (if needed)
# Run down migration
npm run migrate:down
# or
npx prisma migrate reset --to-migration [previous-migration]
Post-Rollback (15-30 minutes)
### Feature Flags
```markdown
## Feature Flag Strategy
### Flag Configuration
```yaml
feature_flags:
new_dashboard:
enabled: false
rollout:
- percentage: 10
start_date: 2025-12-17
- percentage: 50
start_date: 2025-12-20
- percentage: 100
start_date: 2025-12-24
kill_switch: true
// Using LaunchDarkly, Split.io, or custom solution
if (featureFlags.isEnabled('new_dashboard', userId)) {
return renderNewDashboard();
} else {
return renderOldDashboard();
}
10% - Internal Users (Day 1-3)
50% - Beta Users (Day 4-7)
100% - All Users (Day 8+)
### Migration Steps
```markdown
## Database Migration
### Schema Changes
```sql
-- Migration Up (20251217_add_user_preferences.sql)
CREATE TABLE user_preferences (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
preferences JSONB NOT NULL DEFAULT '{}',
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_user_preferences_user_id ON user_preferences(user_id);
-- Migration Down
DROP TABLE IF EXISTS user_preferences;
Pre-deployment (30 minutes before)
# Backup database
pg_dump -h host -U user -d database > backup_$(date +%Y%m%d_%H%M%S).sql
Deployment Window
# 1. Run migrations
npm run migrate:up
# 2. Deploy application
kubectl set image deployment/app app=org/app:v2.0.0 -n production
# 3. Wait for rollout
kubectl rollout status deployment/app -n production
Post-deployment Verification
# Check migration status
npm run migrate:status
# Verify data integrity
psql -c "SELECT COUNT(*) FROM user_preferences;"
# Test endpoints
curl https://api.example.com/health
---
## Common Workflows
### Creating a Feature PR
```bash
# 1. Create and checkout feature branch
git checkout -b feature/PROJ-123-new-dashboard
# 2. Make changes and commit
git add .
git commit -m "feat(dashboard): add user activity widget"
# 3. Push branch
git push -u origin feature/PROJ-123-new-dashboard
# 4. Create PR via GitHub CLI
gh pr create \
--title "[PROJ-123] Feature: Add user activity dashboard" \
--body "$(cat .github/pull_request_template.md)" \
--label "feature,needs-review" \
--reviewer team-lead,code-owner
# 5. Update Jira
# PR link automatically added via GitHub-Jira integration
# 1. Make requested changes
git add .
git commit -m "fix: address review feedback"
# 2. Rebase if main has updates
git fetch origin
git rebase origin/main
# 3. Force push (safe because it's your branch)
git push --force-with-lease
# 4. Respond to review comments
gh pr comment 123 --body "Updated per your feedback!"
# 5. Re-request review
gh pr ready 123
# 1. Final checks
gh pr checks 123
# 2. Update Jira status
# (Automated via webhook)
# 3. Merge via GitHub
gh pr merge 123 --squash --delete-branch
# 4. Update local main
git checkout main
git pull origin main
# 5. Verify deployment (if auto-deploy enabled)
kubectl get pods -n production
# 6. Close Jira ticket
# (Automated via webhook)
# 1. Update main
git checkout main
git pull origin main
# 2. Rebase feature branch
git checkout feature/PROJ-123-feature
git rebase main
# 3. Resolve conflicts
# Edit conflicted files, then:
git add .
git rebase --continue
# 4. Force push
git push --force-with-lease origin feature/PROJ-123-feature
# 1. Check failure logs
gh run view [run-id]
# 2. Run tests locally
npm test
npm run lint
npm run type-check
# 3. Fix issues and push
git add .
git commit -m "fix: resolve CI failures"
git push origin feature/PROJ-123-feature
If reviewer says "PR too large":
# 1. Create feature branch for series
git checkout -b feature/PROJ-123-new-feature-base
# 2. Create sub-branches for logical chunks
git checkout -b feature/PROJ-123-part-1-models
# Make changes, commit, push
# 3. Create first PR against base branch
gh pr create --base feature/PROJ-123-new-feature-base
# 4. Repeat for each logical chunk
git checkout feature/PROJ-123-new-feature-base
git checkout -b feature/PROJ-123-part-2-api
# Continue...
# 5. Final PR merges base into main
gh pr create --base main
Last Updated: 2025-12-17 Skill Version: 1.0.0 Maintained By: Claude Orchestration Team