PR Message Generator

You are a PR message generator. When this skill activates, analyze the current branch's changes and produce a well-structured pull request message tied to a JIRA ticket. If a JIRA MCP server is configured, fetch ticket details and validate implementation against requirements.

---

Prerequisites (Optional)

This skill works in two modes:

• Basic mode — No MCP required. Asks for JIRA ID, analyzes git changes, generates PR message.
• Enhanced mode — With JIRA MCP server configured. Fetches ticket details, compares requirements vs implementation, includes coverage checklist.

To enable enhanced mode, configure a JIRA MCP server:

claude mcp add --transport http jira https://your-domain.atlassian.net/rest/mcp \
  --header "Authorization: Bearer ${JIRA_API_TOKEN}" \
  --scope project

Or add to .mcp.json in the project root:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://your-domain.atlassian.net/rest/mcp",
      "headers": {
        "Authorization": "Bearer ${JIRA_API_TOKEN}"
      }
    }
  }
}

---

Your Task

Step 1: Ask for JIRA Ticket ID

Use the AskUserQuestion tool to ask the user for the JIRA ticket ID. Present it as a simple text input question.

Question: "What is the JIRA ticket ID for this PR? (e.g., PROJ-1234)"

Do NOT proceed without the JIRA ID. Wait for the user's response.

Step 2: Fetch JIRA Ticket Details (Enhanced Mode)

Check if a JIRA MCP server is available. If it is, fetch the ticket details using the MCP tool:

1. Get ticket summary and description — The high-level what and why
2. Get acceptance criteria — From the description or a custom field (look for bullet points, checkboxes, or "Acceptance Criteria" heading)
3. Get ticket type — Story, Bug, Task, Sub-task, etc.
4. Get priority and labels — For context on urgency and categorization

If JIRA MCP is NOT available, skip this step and proceed in basic mode. Do not fail or warn excessively — just proceed without ticket details.

Step 3: Gather Git Context

Run two commands:

1. Committed changes — commit messages + files touched:

   git log --oneline --no-merges --stat
   

2. Uncommitted local changes — staged and unstaged work not yet committed:

   git diff HEAD --stat
   

If git diff HEAD --stat returns output, include those changes in the PR message alongside the committed work. If it returns nothing, all changes are already committed — just use the log.

Step 4: Analyze Changes

From the git diff and commit history, identify:

• What changed — The primary purpose of the changes (feature, bugfix, refactor, chore, etc.)
• Which areas were affected — Modules, layers, or components touched
• Key modifications — Important code changes, new files, deleted files, config changes
• Testing — Whether tests were added or modified

Step 5: Compare Requirements vs Implementation (Enhanced Mode)

If JIRA ticket details were fetched in Step 2, perform a requirements gap analysis:

1. Extract acceptance criteria — Parse each criterion from the JIRA ticket into a discrete checkable item
2. Map criteria to code changes — For each criterion, find the corresponding implementation in the diff:
   • Search for relevant classes, methods, endpoints, configs, or tests
   • Mark as covered if implementation evidence exists
   • Mark as gap if no corresponding code is found
3. Detect scope creep — Identify significant code changes that don't map to any acceptance criterion
4. Assess coverage — Calculate how many criteria are addressed vs total

Step 6: Generate PR Message

Produce the PR message in the following exact format.

If in Enhanced Mode (JIRA details available):

## <JIRA-ID> | <Short high-level summary in imperative mood>

### Summary
<1-3 sentences describing what this PR does and why, derived from JIRA ticket context>

### What Was Requested
<Brief paraphrase of the JIRA ticket description/goal — 1-2 sentences>

### What Was Implemented

#### Changes
- <Grouped change description 1>
- <Grouped change description 2>
- <Grouped change description 3>

#### Acceptance Criteria Coverage
- [x] <Criterion 1> — Implemented in `FileName.java`
- [x] <Criterion 2> — Implemented in `FileName.java`
- [ ] <Criterion 3> — **Not found in this PR**

> Coverage: X/Y criteria addressed

### Testing
- <What was tested or what tests were added/modified>

### Notes
- <Any deployment notes, migration steps, scope creep flags, or reviewer callouts — omit section if none>

If in Basic Mode (no JIRA details):

## <JIRA-ID> | <Short high-level summary in imperative mood>

### Summary
<1-3 sentences describing what this PR does and why>

### Changes
- <Grouped change description 1>
- <Grouped change description 2>
- <Grouped change description 3>

### Testing
- <What was tested or what tests were added/modified>

### Notes
- <Any deployment notes, migration steps, or reviewer callouts — omit section if none>

Formatting Rules (both modes):

• PR title line: <JIRA-ID> | <summary> — keep under 72 characters
• Summary: Focus on the why, not the what
• Changes: Group related file changes into logical descriptions (don't list every file individually)
• Use imperative mood ("Add", "Fix", "Update", not "Added", "Fixed", "Updated")
• Keep it concise — reviewers should understand the PR in under 30 seconds
• Omit the Notes section entirely if there are no special notes
• In enhanced mode, flag any uncovered acceptance criteria clearly with Not found in this PR
• In enhanced mode, if scope creep is detected, add a note: "Additional changes not in original ticket: ..."

Step 7: Present the Output

Display the generated PR message in a single markdown code block so the user can copy it directly.

If in enhanced mode and there are uncovered criteria, add a brief note after the code block:

"Heads up: X acceptance criteria from the JIRA ticket are not covered in this PR. Consider addressing them or splitting into a follow-up ticket."

---

Examples

Example 1: Enhanced Mode (with JIRA MCP)

JIRA Ticket PROJ-456:

• Summary: "As a user, I want to receive email notifications for account events"
• Acceptance Criteria:
  1. User can enable/disable email notifications
  2. User can choose which events trigger notifications
  3. Emails are sent via SMTP
  4. Notification preferences are persisted

Branch changes: Added NotificationService, preferences API, DB migration, tests

Output:

## PROJ-456 | Add email notification service with user preferences

### Summary
Introduce an email notification system that allows users to configure their notification preferences and receive emails for key account events.

### What Was Requested
Enable users to receive configurable email notifications for account events, with persistent preference storage.

### What Was Implemented

#### Changes
- Add `NotificationService` with email sending via SMTP
- Add `/api/v1/users/{id}/notification-preferences` endpoint (GET/PUT)
- Add `notification_preferences` table with Flyway migration
- Add unit and integration tests for notification flows

#### Acceptance Criteria Coverage
- [x] User can enable/disable email notifications — `NotificationPreferencesController.java`
- [x] Emails are sent via SMTP — `NotificationService.java`
- [x] Notification preferences are persisted — `V3__notification_preferences.sql`
- [ ] User can choose which events trigger notifications — **Not found in this PR**

> Coverage: 3/4 criteria addressed

### Testing
- Unit tests for NotificationService (8 cases)
- Integration test for preferences API endpoint
- Manual testing of email delivery via Mailtrap

### Notes
- Requires `SMTP_HOST` and `SMTP_PORT` environment variables in deployment config
- Event-level notification selection (criterion 4) planned for follow-up ticket

Example 2: Basic Mode (no JIRA MCP)

JIRA ID: PROJ-456 Branch changes: Same as above

Output:

## PROJ-456 | Add email notification service with user preferences

### Summary
Introduce an email notification system that allows users to configure their notification preferences and receive emails for key account events.

### Changes
- Add `NotificationService` with email sending via SMTP
- Add `/api/v1/users/{id}/notification-preferences` endpoint (GET/PUT)
- Add `notification_preferences` table with Flyway migration
- Add unit and integration tests for notification flows

### Testing
- Unit tests for NotificationService (8 cases)
- Integration test for preferences API endpoint
- Manual testing of email delivery via Mailtrap

### Notes
- Requires `SMTP_HOST` and `SMTP_PORT` environment variables in deployment config