/github-pr-description

name: github-pr-description
description: 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.

Create PR Description

Generate comprehensive pull request descriptions and create PRs using GitHub CLI.

Workflow

1. Verify Prerequisites

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.

2. Analyze Changes

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.

3. Determine Change Type

Classify the PR into one of these categories:

• **fix**: Bug fixes, error corrections, resolving issues
• **feature**: New functionality, capabilities, or enhancements
• **performance**: Speed improvements, optimization, efficiency gains
• **refactor**: Code restructuring without changing behavior
• **docs**: Documentation changes
• **test**: Test additions or improvements
• **chore**: Maintenance tasks, dependencies, configuration

Base this on:

• Commit messages (keywords like "fix", "add", "optimize", "refactor")
• Nature of code changes (new files = feature, test fixes = fix, etc.)
• Scope of changes

4. Generate Description

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)

Description Guidelines

**Essential Elements:**

• **Summary**: One clear sentence explaining the change and its value
• **Context**: Why this change was needed, what problem it solves
• **Changes**: What was actually changed at a high level
• **Testing**: How reviewers can verify the changes

**Optional but Recommended:**

• **Implementation Details**: For complex changes, explain the technical approach
• **Use Cases**: Concrete examples of how the feature will be used
• **Links**: Related issues, documentation, papers, or original implementations
• **Known Issues**: Any limitations or known problems

**What to Avoid:**

• Empty descriptions or just issue links
• Placeholder text like "Fixes #(issue)"
• File-by-file breakdowns (unless necessary)
• Low-level implementation details (keep it high-level)
• Boilerplate statements
• Personal checklists as the main description

Description Examples

**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"}'

Links

• Related issues: #123, #456
• Documentation: /docs/semantic-search.md

**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

Links

• Related