PR Description Writer Skill
Purpose
Write and verify GitHub pull request descriptions following project templates with zero fabrication tolerance. Ensures all claims are backed by actual code changes and applies technical documentation verification standards to prevent marketing language and unverified claims.
Two Modes of Operation
Create Mode (Default)
Generate new PR description from git changes:
- Analyze git diff and commit history
- Follow project PR template if found
- Verify all claims against actual changes
- Generate markdown for
gh pr create --body
Verify Mode
Audit existing PR description for accuracy:
- Compare description claims against git changes
- Flag fabricated features or unverified claims
- Identify marketing language
- Report verification findings
Core Workflow
Quick 5-Phase Process
- Template Discovery - Find PR template in .github/ or docs/
- Change Analysis - Analyze git diff and commit history
- Description Generation - Populate template sections with verified content
- Verification - Run comprehensive verification checklist (P0/P1/P2)
- Output Generation - Generate final PR description with verification metadata
For detailed step-by-step instructions for each phase, see references/WORKFLOW-PHASES.md.
Template Sections Reference
Standard Sections (Industry Best Practices 2025)
Required Sections
- Summary - Brief overview (1-3 bullets)
- Changes - Technical details of modifications
- Testing - How changes were tested
- Related Issues - Closes/Fixes/Relates to syntax
- Checklist - Pre-submission verification
Conditional Sections
- Breaking Changes - Only if backwards-incompatible
- Migration Guide - If breaking changes exist
- Performance Impact - Only with benchmark evidence
Optional Sections
- Screenshots - For UI changes
- Security Considerations - For security-related changes
- Deployment Notes - Special deployment instructions
- Rollback Plan - How to revert if needed
Critical Verification Rules
Zero Fabrication Policy - Must Verify Against git diff
P0 - CRITICAL (Block PR Creation):
- Never fabricate features, files, methods, or APIs
- Never claim performance improvements without benchmarks
- Never fabricate test coverage numbers
- All code references must match git diff
P1 - HIGH (Should Fix):
- No marketing buzzwords (enterprise, blazing, cutting-edge, etc.)
- No decorative emojis in technical text
- Technical descriptions only
For detailed verification rules with examples and violations, see references/VERIFICATION-RULES.md.
Common Issues and Solutions
Issue: Nil Pointer in Template Parsing
Problem: Template has nested YAML front matter
Solution: Parse only markdown headers, ignore YAML
Issue: Multiple PR Templates
Problem: .github/PULL_REQUEST_TEMPLATE/ contains multiple files
Solution: Use default.md or ask user which template
Issue: No Git History Available
Problem: New repository or shallow clone
Solution: Require full git history, inform user
Issue: Conflicting Commit Messages
Problem: Commits say different things about same change
Solution: Analyze actual code changes, use most recent commit message
Integration with Other Skills
Invoked By:
- create-pr skill (Step 6: Generate PR Description)
- User (manual invocation)
Invokes:
- None (uses git commands via Bash tool)
Works With:
- check-history - Provides git context
- api-documentation-verify - Verification pattern reference
- safe-commit - Commit messages already verified
Integration in create-pr Flow:
Before (current):
create-pr Step 6: Generate PR description (embedded logic)
After (new):
create-pr Step 6: Invoke pr-description-writer skill
├─> Input: base branch, commit range, template
├─> Process: Analyze, verify, generate
└─> Output: Verified PR description markdown
Example Usage
Automatic Invocation (via create-pr)
User: "create a PR"
Assistant: [create-pr invokes pr-description-writer automatically]
# pr-description-writer executes:
# 1. Finds .github/PULL_REQUEST_TEMPLATE.md
# 2. Analyzes git diff main...feature-branch
# 3. Generates verified description
# 4. Returns to create-pr for gh pr create
Manual Creation
User: "write a PR description for my changes"
Assistant: "I'll use pr-description-writer to create a verified PR description"
# Skill executes in create mode:
# 1. Discovers template
# 2. Analyzes current branch vs main
# 3. Generates description
# 4. Outputs markdown
Verification Mode
User: "verify the PR description for #47"
Assistant: "I'll verify the PR description against actual changes"
# Skill executes in verify mode:
# 1. Fetches PR description from GitHub
# 2. Gets PR branch and diff
# 3. Verifies all claims
# 4. Reports findings
Time Estimates
Create Mode:
- Small PR (1-5 files, 1-3 commits): 10-15 minutes
- Medium PR (5-15 files, 3-10 commits): 15-25 minutes
- Large PR (15+ files, 10+ commits): 25-40 minutes
Verify Mode:
- Review existing description: 5-10 minutes
Success Criteria
A PR description is complete and verified when:
- ✅ All template sections populated accurately
- ✅ All claims verified against git diff
- ✅ No fabricated features or methods
- ✅ No unverified performance claims
- ✅ No fabricated timing numbers
- ✅ No marketing language or buzzwords
- ✅ Test coverage numbers match actual results (or not specified)
- ✅ All mentioned files exist in git diff
- ✅ Breaking changes documented accurately (if any)
- ✅ Related issues linked correctly
- ✅ Checklist reflects actual status
- ✅ Technical descriptions only
- ✅ Verification metadata included
Output Format
Create Mode Output
[Complete PR description following template]
<!-- All sections populated -->
<!-- All claims verified -->
<!-- Ready for gh pr create --body -->
Verify Mode Output
## PR Description Verification Report
**PR**: #47
**Status**: ✅ PASSED / ⚠️ WARNINGS / ❌ FAILED
### P0 Issues (Must Fix)
- None
### P1 Issues (Should Fix)
- Line 15: Marketing buzzword "enterprise-grade"
- Line 23: Unverified performance claim "10x faster"
### P2 Issues (Consider)
- Breaking changes section could be more detailed
### Recommendations
1. Remove marketing language
2. Replace performance claim with architectural fact
3. Expand breaking changes documentation
**Files Verified**: 12 files
**Claims Verified**: 18 claims
**Verification Date**: 2025-01-12T10:30:00Z
References
- Technical Documentation Expert Agent (verification patterns)
- API Documentation Verify Skill (verification checklist)
- GitHub PR Best Practices: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests
- Semantic PR Guidelines: https://www.conventionalcommits.org/
- Zero Fabrication Policy: Based on technical-documentation-expert (lines 13-35, 239-340)
Maintained by: Engineering team Review Schedule: Quarterly Last Updated: 2025-01-12