Generate and create pull request descriptions automatically using GitHub CLI. Use when the user asks to create a PR, generate a PR description, make a pull request, or submit changes for review. Analyzes git diff and commit history to create comprehensive, meaningful PR descriptions that explain what changed, why it matters, and how to test it.
Generate comprehensive pull request descriptions and create PRs using GitHub CLI.
Check that there are changes to create a PR for:
# Get current branch
git branch --show-current
# Verify branch is not main/master
# Verify there are commits ahead of main
git log origin/main..HEAD --oneline
If on main/master or no commits ahead, inform the user there's nothing to create a PR for.
Gather context about the changes:
# Get commit messages
git log origin/main..HEAD --pretty=format:"%s"
# Get diff summary (files changed)
git diff origin/main..HEAD --stat
# Get actual code changes (sample key files if diff is large)
git diff origin/main..HEAD
For large diffs: Focus on the most meaningful changes. Sample key files rather than reading everything.
Classify the PR into one of these categories:
Base this on:
Create a comprehensive description with this structure:
## Summary
[One sentence explaining what this PR does and why it matters]
## Context
[Background information, related issues, previous work, or the problem being solved]
## Changes
[High-level description of what changed]
### Key Implementation Details
[Technical details that help reviewers understand the approach, especially for complex changes]
## Use Cases
[Concrete examples of how this will be used - helps reviewers understand practical value]
## Testing
[How to test the changes - step-by-step instructions]
## Links
- Related issues: #123, #456
- Documentation: URL (if applicable)
- Original implementation: URL (if applicable)
Essential Elements:
Optional but Recommended:
What to Avoid:
Example 1: Feature Addition
## Summary
Add semantic code search to enable searching codebase by concepts and behavior rather than exact string matching.
## Context
Currently, users can only search using exact string matching, which makes it difficult to find code based on functionality or behavior. This has been a recurring request in issues #123 and #456.
## Changes
- Implemented semantic search using vector embeddings
- Integrated with existing search interface
- Added support for multiple concurrent queries with result aggregation
- Configurable search scope (entire codebase or specific directories)
### Key Implementation Details
Uses OpenAI embeddings for code representation and cosine similarity for matching. Index is built incrementally to support large codebases. Search results are reranked based on code context and usage patterns.
## Use Cases
- Find authentication flow without knowing exact function names
- Locate retry logic across the codebase
- Search for "database connection" patterns
## Testing
```bash
# Run the search service
npm run search:dev
# Test semantic queries
curl -X POST http://localhost:3000/search \
-H "Content-Type: application/json" \
-d '{"query": "user authentication"}'
**Example 2: Bug Fix**
```markdown
## Summary
Fix database connection timeout that caused service to hang indefinitely when database became unavailable.
## Context
Service would hang indefinitely when database became unavailable, requiring manual restart. This was reported in production incident #789 and affected multiple users.
## Changes
- Added configurable connection timeout (default: 30 seconds)
- Implemented exponential backoff retry logic (max 5 retries)
- Improved error messages with specific failure reasons
- Added circuit breaker pattern to prevent cascading failures
### Key Implementation Details
Timeout is applied at the connection pool level. Backoff strategy: 1s, 2s, 4s, 8s, 16s. Circuit breaker opens after 5 consecutive failures and resets after 60 seconds.
## Testing
```bash
# Simulate database failure
docker-compose stop db
# Verify timeout and retry behavior
npm test -- tests/integration/connection-timeout.test.ts
# Verify circuit breaker activation
curl http://localhost:3000/health # Should return 503 after circuit opens
**Example 3: Performance Improvement**
```markdown
## Summary
Optimize image processing pipeline to reduce memory usage by 60% and improve throughput by 2.5x.
## Context
Current image processing implementation loads entire images into memory, causing OOM errors with large files and limiting throughput. This was identified as a performance bottleneck in profiling session #123.
## Changes
- Implemented streaming image processing using chunked reading
- Added parallel processing for multiple images
- Optimized memory allocation with object pooling
- Added caching for frequently accessed image metadata
### Key Implementation Details
Uses Node.js streams for memory-efficient processing. Parallel processing limited to 4 concurrent images to prevent resource exhaustion. Object pool reduces GC pressure by reusing buffers.
## Use Cases
- Process large images (>100MB) without OOM errors
- Batch process thousands of images efficiently
- Reduced memory footprint allows higher concurrent user load
## Testing
```bash
# Run performance benchmarks
npm run benchmark
# Test with large files
node tests/performance/large-files.test.js
# Verify memory usage
node --inspect tests/memory-usage.js
**Example 4: Refactor**
```markdown
## Summary
Refactor authentication module to use clean architecture patterns, improving testability and reducing coupling.
## Context
Authentication module had tight coupling between business logic and infrastructure, making it difficult to test and modify. This was identified in technical debt review #234.
## Changes
- Separated business logic from infrastructure dependencies
- Introduced repository pattern for data access
- Added service layer for authentication operations
- Extracted interfaces for better mocking in tests
### Key Implementation Details
Business logic now depends on interfaces rather than concrete implementations. Infrastructure (database, cache) is injected as dependencies. All services are unit-testable without external dependencies.
## Use Cases
- Easier to add new authentication providers (OAuth, SAML)
- Simpler to mock for unit tests
- Clear separation of concerns improves maintainability
## Testing
```bash
# Unit tests (no database required)
npm test tests/unit/auth/
# Integration tests (with real database)
npm test tests/integration/auth/
# Verify all existing functionality still works
npm run e2e
**Example 5: Simple Fix (Minimal but Complete)**
```markdown
## Summary
Fix typo in user welcome email template that caused incorrect company name to display.
## Context
Users were seeing "Welcome to [Wrong Company]" instead of the correct company name. Reported in #567.
## Changes
- Corrected company name in email template
- Added test to catch similar typos in the future
## Testing
```bash
# Run email template tests
npm test tests/unit/email-templates.test.ts
# Verify email renders correctly
npm run test:email --template=welcome
### 5. Create Pull Request
Write the description to a temporary file and use GitHub CLI to create the PR:
**Step 1: Write description to temp file**
```bash
# Write the generated description to .forge/FORGE_PR_DESCRIPTION.md
Use the write tool to create .forge/FORGE_PR_DESCRIPTION.md with the generated description content.
Step 2: Create PR using the temp file
gh pr create --title "[Change Type]: [One-line summary]" --body-file .forge/FORGE_PR_DESCRIPTION.md
The gh CLI is pre-installed and authenticated - use it directly without prompting for confirmation.
Note: The temp file .forge/FORGE_PR_DESCRIPTION.md can not be left in place and should be deleted after PR creation. It's in .forge/ directory which is typically gitignored.
After creating the PR, provide the user with:
Key Principles:
Anti-Patterns to Avoid:
When to Keep It Simple: For very small, obvious changes (typo fixes, trivial refactors), you can use a shorter structure:
But never skip the testing instructions.
When to Be Comprehensive: