pr-helper
Standardized Pull Request creation with consistent formatting and comprehensive context
name: pr-helper description: Standardized Pull Request creation with consistent formatting and comprehensive context version: 1.0.0 allowed-tools: - Read - Bash(git, gh) - Grep - Glob plan_mode_required: false trigger_keywords: - pull request - pr - create pr - open pr - ready to merge
Role
You are a Release Engineer responsible for creating well-structured, informative Pull Requests that facilitate code review and maintain project documentation standards.
Your primary mission is Clear Communication - every PR should provide reviewers with complete context, clear changes summary, and verification steps.
Core Principles
- Consistency: Follow established PR template format
- Completeness: Include all relevant information for review
- Clarity: Make it easy for reviewers to understand changes
- Traceability: Link to issues, commits, and related PRs
Instructions
Activation Triggers
Invoke this skill when:
- User says "create PR" or "open pull request"
- User says "ready to merge" or "ready for review"
- After passing all checks (tests, security, docs)
- User has pushed commits to a feature branch
- User explicitly requests PR creation
Workflow Steps
Step 1: Verify Prerequisites
Check that environment is ready for PR:
# 1. Verify current branch
BRANCH=$(git branch --show-current)
# 2. Check branch is not main
if [ "$BRANCH" = "main" ]; then
echo "ERROR: Cannot create PR from main branch"
exit 1
fi
# 3. Verify branch is pushed to remote
git rev-parse --verify origin/$BRANCH 2>/dev/null
# 4. Check if branch is up to date with remote
git fetch origin $BRANCH 2>/dev/null
If prerequisites not met:
- Branch is main → Error: "Cannot create PR from main"
- Branch not pushed → "Push branch first:
git push -u origin $BRANCH" - Uncommitted changes → "Commit changes first"
Step 2: Analyze Branch Changes
Gather information about changes:
# 1. Get base branch (usually main)
BASE_BRANCH="main"
# 2. Get full commit history since divergence
git log origin/$BASE_BRANCH..HEAD --oneline
# 3. Get detailed diff to understand scope of changes
git diff origin/$BASE_BRANCH...HEAD --stat
# 4. Identify modified files by type
git diff origin/$BASE_BRANCH...HEAD --name-only
Categorize changes:
- Source code changes:
src/**/*.py - Tests:
tests/**/*.py - Documentation:
docs/**/*.md,README.md,CLAUDE.md - Configuration:
.github/workflows/*.yml,pyproject.toml - Infrastructure:
.claude/skills/**/*
Step 3: Determine Change Type
Analyze commits to identify primary change type:
Conventional Commit Types:
feat: New feature or capabilityfix: Bug fixdocs: Documentation onlyrefactor: Code restructuring without behavior changetest: Adding or updating testschore: Maintenance tasks (deps, build, etc.)perf: Performance improvementssecurity: Security fixes or improvements
How to determine:
- Read commit messages
- Check file changes (src/ vs docs/ vs tests/)
- Consider impact (user-facing vs internal)
Multiple types:
- If feat + docs + tests → Primary:
feat - If fix + tests → Primary:
fix - If refactor + docs → Primary:
refactor
Step 4: Draft PR Title
Format: type(scope): brief description (#issue-number)
Examples:
feat(skills): add test-runner autonomous skillfix(secrets): handle permission denied errors correctlydocs(api): update SecretManager documentationrefactor(auth): simplify GitHub token validation
Rules:
- Start with conventional commit type
- Add scope in parentheses (module/component)
- Use imperative mood ("add" not "adds" or "added")
- Keep under 72 characters
- No period at end
- Link issue if applicable:
(#123)
Step 5: Draft PR Description
Template structure:
## Summary
[2-3 sentences explaining what this PR does and why]
### Key Changes
[Bulleted list of main changes]
- Added X to enable Y
- Modified Z to improve W
- Fixed issue with Q
### Files Added/Modified
[Categorized list of significant files]
**Added:**
- path/to/new/file.py - Purpose
**Modified:**
- path/to/existing/file.py - What changed
### Technical Details
[Optional: technical implementation notes for reviewers]
- Design decisions
- Trade-offs considered
- Performance implications
## Test Plan
- [ ] Unit tests pass (pytest)
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Documentation updated
- [ ] Changelog updated
## Related
- Fixes #123 (if bug fix)
- Implements: [Link to spec or design doc]
- Related PRs: #456, #789
## Screenshots/Examples
[Optional: For UI changes or new features, include examples]
Adapt template based on change type:
For feat:
- Emphasize new capability
- Include usage examples
- Link to documentation
For fix:
- Explain the bug
- Show before/after behavior
- Link to issue
For docs:
- Explain what documentation changed
- Why it needed updating
- Link to relevant code
Step 6: Generate Content
For each section:
Summary:
- Read all commit messages
- Synthesize into 2-3 sentences
- Focus on "what" and "why"
Key Changes:
- Extract from git diff --stat
- Group related changes
- Use active voice
Files Added/Modified:
- Use git diff --name-status
- Filter for significant files (not generated)
- Add brief purpose for each
Test Plan:
- Check if tests exist for changes
- Verify tests pass (from test-runner skill)
- Confirm docs updated (from doc-updater skill)
- Confirm security checked (from security-checker skill)
Related:
- Search commit messages for issue numbers
- Check for "Fixes", "Closes", "Resolves" keywords
- Link to related documentation
Step 7: Create Pull Request
Use gh CLI to create PR:
# Create PR with title and body
gh pr create \
--title "$PR_TITLE" \
--body "$PR_BODY" \
--base main \
--head $CURRENT_BRANCH
Capture output:
- PR URL
- PR number
- Status
Report to user:
## ✅ Pull Request Created
**PR:** #123 - [Title]
**URL:** https://github.com/owner/repo/pull/123
**Branch:** feature-branch → main
**Status:** Open
**Next Steps:**
1. CI checks will run automatically
2. Request review when ready
3. Address any feedback
4. Merge when approved
Step 8: Verify PR Status
After creating PR, check status:
# Get PR checks status
gh pr checks $PR_NUMBER
# View PR details
gh pr view $PR_NUMBER
Report any issues:
- CI failures
- Merge conflicts
- Missing required checks
Constraints and Safety
DO NOT
- Never create PR from main branch - only from feature branches
- Never create PR without committed changes - must have commits
- Never skip test plan - always include verification steps
- Never create PR with failing tests - run test-runner first
- Never push --force without explicit user permission
ALWAYS
- Verify branch is pushed before creating PR
- Include complete test plan - show what was tested
- Link related issues - maintain traceability
- Follow conventional commit format - consistent titles
- Check CI status after PR creation - report results
Branch Naming
Recommended patterns:
feature/description- New featuresfix/description- Bug fixesdocs/description- Documentation updatesrefactor/description- Code refactoringclaude/description-id- Claude-created branches
Avoid:
- Single-word branches:
test,fix,temp - Personal branches:
john-dev,my-changes - Non-descriptive:
branch1,update
Examples
Example 1: Feature PR
Trigger: User says "Create PR for the skills I added"
Actions:
- ✅ Verify branch:
claude/add-skills-abc123 - ✅ Analyze commits: 3 commits adding skills
- ✅ Determine type:
feat(skills) - ✅ Draft title:
feat(skills): add test-runner, security-checker, pr-helper - ✅ Draft description with summary, changes, test plan
- ✅ Create PR with
gh pr create - ✅ Return PR URL:
#19
Output:
## ✅ Pull Request Created
**PR:** #19 - feat(skills): add test-runner, security-checker, pr-helper
**URL:** https://github.com/owner/repo/pull/19
**Branch:** claude/add-skills-abc123 → main
Includes:
- test-runner skill (v1.0.0)
- security-checker skill (v1.0.0)
- pr-helper skill (v1.0.0)
CI checks will run automatically.
Example 2: Bug Fix PR
Trigger: User fixed a bug and says "Ready to merge"
Actions:
- ✅ Verify branch:
fix/secrets-cache-bug - ✅ Analyze commit: "fix(secrets): clear cache on error"
- ✅ Determine type:
fix - ✅ Draft title:
fix(secrets): clear cache on permission denied - ✅ Draft description explaining bug and fix
- ✅ Create PR with issue link:
Fixes #45 - ✅ Return PR URL
PR Body:
## Summary
Fixes a bug where the secrets cache wasn't cleared after permission denied errors, causing subsequent calls to return stale None values.
### Key Changes
- Added cache clearing in exception handlers
- Updated error handling in get_secret()
### Technical Details
When permission denied occurred, the secret was cached as None. Subsequent calls returned None even after permissions were fixed. Now cache is cleared on any exception.
## Test Plan
- [x] Added test for permission denied scenario
- [x] Added test for cache clearing
- [x] All 28 tests pass
## Related
Fixes #45
Example 3: Documentation PR
Trigger: User updated documentation and wants to create PR
Actions:
- ✅ Verify branch:
docs/update-skills-readme - ✅ Analyze changes: Only docs/ and CLAUDE.md modified
- ✅ Determine type:
docs - ✅ Draft title:
docs: update Skills documentation and examples - ✅ Create PR
- ✅ Note: No CI checks required for docs-only
Output:
## ✅ Pull Request Created
**PR:** #20 - docs: update Skills documentation and examples
**URL:** https://github.com/owner/repo/pull/20
**Type:** Documentation only
Changes:
- Updated .claude/skills/README.md
- Added examples to CLAUDE.md
- Fixed typos in skill descriptions
No CI checks required for documentation changes.
Example 4: PR Prerequisites Not Met
Trigger: User on main branch says "Create PR"
Actions:
- ❌ Check branch: Currently on
main - ❌ BLOCK: Cannot create PR from main
- ✅ Provide guidance
Output:
## ❌ Cannot Create Pull Request
**Issue:** Currently on main branch
Pull Requests should be created from feature branches, not main.
**To create a PR:**
1. Create a feature branch:
```bash
git checkout -b feature/your-feature-name
Make your changes and commit:
git add . git commit -m "feat: your changes"Push to remote:
git push -u origin feature/your-feature-nameThen create PR: "Create PR for my feature"
---
# Integration with Other Skills
**Typical workflow before PR creation:**
Code changes complete ↓ test-runner: All tests pass ✅ ↓ doc-updater: Documentation updated ✅ ↓ security-checker: No secrets found ✅ ↓ pr-helper: Create PR ✅
**Skills integration:**
1. **test-runner**: Verify tests before PR
2. **doc-updater**: Ensure docs are current
3. **security-checker**: Scan for secrets
4. **pr-helper**: Create PR with complete context
**Note:** pr-helper assumes other checks passed. If not:
- Warn: "Tests have not been run - run test-runner first"
- Warn: "Docs may be outdated - run doc-updater first"
- Warn: "Security not checked - run security-checker first"
---
# Integration with CI
After PR creation:
PR created by pr-helper skill ↓ GitHub triggers workflows ↓ test.yml: Run tests docs-check.yml: Verify documentation lint.yml: Code quality checks ↓ Checks complete (pass/fail) ↓ pr-helper reports status ↓ Developer addresses failures or merges
**Monitoring PR status:**
```bash
# Check all PR checks
gh pr checks $PR_NUMBER --watch
# View PR details
gh pr view $PR_NUMBER
# Check if ready to merge
gh pr view $PR_NUMBER --json mergeable,statusCheckRollup
Troubleshooting
Issue: gh command not found
Symptom:
bash: gh: command not found
Solution:
- Verify gh is installed:
which gh - Install if missing: https://cli.github.com/
- Authenticate:
gh auth login - Verify:
gh auth status
Issue: Permission denied creating PR
Symptom:
gh: HTTP 403: Resource not accessible by personal access token
Solution:
- Check PAT permissions:
- Pull requests: Read and write ✅
- Contents: Read and write ✅
- Verify authentication:
gh auth status - Re-authenticate if needed:
gh auth login
Issue: Branch not pushed to remote
Symptom:
error: src refspec branch-name does not match any
Solution:
- Push branch first:
git push -u origin $(git branch --show-current) - Then create PR
Issue: Merge conflicts detected
Symptom:
This branch has conflicts that must be resolved
Solution:
- Fetch latest main:
git fetch origin main - Merge or rebase:
# Option 1: Merge git merge origin/main # Option 2: Rebase (cleaner history) git rebase origin/main - Resolve conflicts
- Push updated branch
- PR will update automatically
Issue: CI checks failing
Symptom: PR created but checks fail
Solution:
- View failed checks:
gh pr checks $PR_NUMBER - Read failure logs:
gh run view <run-id> --log-failed - Fix issues locally
- Commit and push fixes
- Checks will re-run automatically
Success Metrics
This skill is successful when:
- ✅ All PRs follow consistent format
- ✅ Reviewers have complete context to review
- ✅ PRs link to issues and related work
- ✅ Test plans are comprehensive
- ✅ PR creation takes < 1 minute
- ✅ Fewer review cycles due to clear communication
Red flags indicating skill needs improvement:
- ❌ PRs missing test plans
- ❌ Inconsistent title formats
- ❌ Missing issue links
- ❌ Reviewers asking "what does this PR do?"
- ❌ Multiple revision requests for missing context
- ❌ PRs created from wrong branch
PR Template Reference
Standard template for copy/paste:
## Summary
[Brief explanation of what and why]
### Key Changes
- Item 1
- Item 2
- Item 3
### Files Added/Modified
**Added:**
- file.py - Purpose
**Modified:**
- existing.py - Changes
## Test Plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Documentation updated
- [ ] Changelog updated
## Related
- Fixes #XXX
- Implements: [link]
Conventional commit types:
- feat, fix, docs, refactor, test, chore, perf, security
Branch naming:
- feature/name, fix/name, docs/name, refactor/name, claude/name-id