Generate PR Description

Generate a concise pull request description by analyzing git changes and using the project's PR template.

Language: Always generate PR titles and descriptions in English, regardless of the user's language or the language of commit messages.

Workflow

1. Identify parent branch

   • Check current branch: git rev-parse --abbrev-ref HEAD
   • Determine parent (usually main or master): git show-branch | grep '*' | grep -v "$(git rev-parse --abbrev-ref HEAD)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//'
   • Or use: git merge-base HEAD main to find common ancestor

2. Analyze changes

   • Get diff stats: git diff --stat <parent-branch>..HEAD
   • Get commit messages: git log --oneline <parent-branch>..HEAD
   • Get file changes: git diff --name-status <parent-branch>..HEAD

3. Generate semantic commit title

   • Analyze changes to determine type:
     • feat: - New features
     • fix: - Bug fixes
     • docs: - Documentation changes
     • style: - Code style changes (formatting, no logic change)
     • refactor: - Code refactoring
     • perf: - Performance improvements
     • test: - Adding or updating tests
     • chore: - Maintenance tasks (deps, config, etc.)
   • Format: <type>(<scope>): <short description>
   • Keep title under 72 characters

4. Load PR template

   • Check for .github/pull_request_template.md first
   • If not found, check .gitlab/merge_request_template.md
   • If still not found, use the template in this skill: templates/pull_request_template.md (relative to the skill directory)
   • Read the template file

5. Fill template concisely

   • Before filling the template, group all changes by theme/area (e.g. auth, API, UI, tests, docs)
   • Do not repeat the same subject: one entry per theme, even if multiple files or commits touch it
   • Extract key changes from git diff and commits, already grouped by theme as above
   • Fill "Changes Description" using the template’s two-level structure:
     • Level 1 (category): one top-level bullet per theme/area ({level1_changes_description_category})
     • Level 2 (sub-details): one or more sub-bullets under each category for distinct sub-changes ({level2_change_detail_for_that_category}); omit sub-bullets when a category has only one simple change
   • Keep each bullet point brief (one line when possible)
   • Use emojis sparingly (🚧 for WIP, ✅ for done, etc.)
   • Mark checklist items appropriately:
     • Documentation: check the box if the PR introduces documentation (JSDoc in changed files, or markdown files .md detected in the diff).
     • Tests: check the box if the PR adds or updates unit tests. Detect test changes using common conventions: file names matching *.test.* or *.spec.*, or paths under test/, __tests__/, tests/, or similar directories used by mainstream test runners (do not assume a specific framework such as Jest or Vitest).
   • Related Issue(s) – see step 6 below. Leave "Screen capture(s)" as 🚫 if not applicable

6. Related tickets

   • Ticket IDs source: The user may provide ticket IDs in their request (e.g. "generate PR description, tickets: NN-123, TB-456" or "PR description with NN-123, TB-456"). Treat any such IDs as the company tracking system ticket numbers for this PR. If none were given, ask the user: “Ticket IDs for this PR (comma-separated, e.g. PROJ-123, PROJ-456). Leave empty if none.”
   • Parsing: From the user message, accept ticket IDs in forms like: tickets: NN-123, TB-456; tickets NN-123, TB-456; or inline project-key numbers (e.g. NN-123, TB-456). Normalize to a list of trimmed IDs (comma/semicolon/space separated).
   • If one or more IDs are available (from the request or from the user's answer):
     • Tasks manager base URL: Run from the project root (repo where the PR is created): node <skill-dir>/scripts/tasks-system.mjs. The script loads skills-configs.json at project root (creates it if missing), prompts for any missing known keys, and outputs the full config as JSON (key/value). Use configs.tasksManagerSystemBaseUrl for the base URL of ticket links.
     • For each ticket ID (trimmed), build the link: {baseUrl}/{ID}
     • Description: If you can get the issue summary (e.g. API or user pastes descriptions), use it as the link text; otherwise use the ticket ID.
     • Fill "Related Issue(s)" with a markdown list, one line per ticket:
       • - [Description or ID]({baseUrl}/{ID})
       • Example: - [Add login screen](https://company.atlassian.net/browse/PROJ-123) or - [PROJ-123](https://company.atlassian.net/browse/PROJ-123)
   • If the user leaves the list empty or says “none”, keep "Related Issue(s)" as - 🚫.

7. Enforce 1000 character limit

   • Count total characters including markdown syntax
   • If over limit, prioritize:
     1. Keep the title
     2. Keep essential change descriptions
     3. Shorten or remove less critical sections
     4. Condense bullet points

8. Write file, copy to clipboard, remove file

   • At PR project root, create or overwrite pr-description.md with the full PR output (complete markdown from "## PR Description" through the end of the description).
   • Call the copy script with the full path to the file: node <skill-dir>/scripts/copy-to-clipboard.mjs "<full-path-to-pr-description.md>" (e.g. $(pwd)/pr-description.md when run from the PR project).
   • On success: remove the file (rm pr-description.md) and tell the user: "The full PR description is in the clipboard; you can paste it into your PR."
   • On error: leave pr-description.md in place and tell the user they can open it or copy manually.

Output Format

Provide ready-to-copy markdown in this format:

## PR Description

<semantic-commit-style-title>

<filled-template-markdown including Summary then Changes Description with level-1 bullets (themes) and optional level-2 sub-bullets (sub-changes)>

Grouping rule: Never list the same subject twice. If several commits or files relate to the same theme (e.g. "auth", "tests", "docs"), merge them into a single level-1 bullet in the summary and in Changes Description; use level-2 sub-bullets only for distinct sub-changes within that theme.

Example

Input analysis:

• Branch: feature/add-user-auth
• Changes: Added login component, updated auth service, added tests
• 3 commits: "feat: add login component", "feat: update auth service", "test: add auth tests"

Output:

## Changes Description

feat(auth): implement user authentication

- **Auth:** login component and auth service.
  - Login component added.
  - Auth service updated.
- **Tests:** auth tests added.

## Checklist

(other checklist items...)

Character Count Tips

• Use abbreviations when appropriate (e.g., "auth" instead of "authentication")
• Combine related changes into single level-1 bullets; use level-2 sub-bullets only when a category has several distinct sub-changes (grouping avoids repetition)
• Remove template placeholders if not needed
• Prioritize Summary and "Changes Description" over other sections