name: pr-description
description: Generate a structured, reviewer-friendly PR description based on current branch changes and project context

PR Description Skill

This skill generates a clear, structured, and reviewer-friendly PR description based on the current branch's changes, diffs, and relevant project files.

Key Point: Automatically help organize PR descriptions, but do not randomly modify code or fix bugs on your own. Focus on "explaining what this PR does and what its impact is."

When to Use

• When preparing to submit a PR from the current branch to main / develop / other upstream branches
• After completing main development and self-testing, when about to write PR descriptions
• When you want PR descriptions to have a fixed format (Summary / Changes / Behavior / Risks / Test Plan)
• When you want reviewers to understand the PR's purpose and impact at a glance

Output Requirements

Generated content must be in Markdown format and use the following fixed structure (all sections required):

• ## Summary

• 2–4 bullet points explaining the PR's "core purpose" and "main achievements"

• ## Changes

• Grouped by module / feature / file groups (using ### subheadings)

• Each section uses bullet points to describe actual changes (do not paste large code blocks, only describe what was done)

• ## Behavior / Compatibility

• Explain behavioral changes, backward compatibility, whether old version logic is preserved (e.g., v1 vs v2 coexistence)
• If there are API / CLI interface changes, explicitly mention them

Style requirements:

• Use English for descriptions, keep file names, classes, functions, CLI parameters in English
• Use - for bullet points, bold important keywords (e.g., - **Command**: ...)
• Do not paste long source code, only describe logic and behavior
• Do not make up stories: only describe based on actual changes

Information Gathering Guidelines

Before generating PR descriptions, make good use of information available in Cursor (but do not modify any files or execute destructive commands yourself):

• Priority references:
• git diff / changed files between current branch and target branch
• Related management commands / service / library files (e.g., apps/nist/management/commands/nist_cpe_handle_v2.py, apps/nist/lib/cpe_search_v2.py, apps/nist/lib/normalize_data_v2.py, etc.)
• Corresponding design / documentation files (e.g., apps/nist/management/commands/v2.md)
• If this PR only modifies a small area (e.g., a single command or single service), clearly indicate "main impact scope" in Summary and Changes
• If this PR is detected as an extension of a previous PR (e.g., v2 weight adjustment, algorithm refinement), you can briefly mention "continuing from previous version, fine-tuning XXX" in Summary

Instructions

When this Skill is triggered, follow these steps to generate PR descriptions:

Step 1: Understand Change Scope

• Based on available information (file diffs, open files, related documentation), answer the following questions:
• Which functional area does this PR mainly modify? (e.g., NIST CPE query v2, report export, API permissions, etc.)
• Are there new / modified CLI commands, APIs, database schemas, background schedules?
• Are there new or updated documentation files (e.g., v2.md)?
• Only organize in your mind, do not output lengthy analysis text into the PR description.

Step 2: Organize Title and Summary

• Choose appropriate prefix based on change nature:
• feat: for new features
• fix: for bug fixes
• refactor: for refactoring or internal adjustments without behavior changes
• docs: for documentation-focused changes
• ## Summary section:
• Focus on "why this PR exists" and "the most important 2–4 change points"
• Each point describes one thing, avoid cramming details

Step 3: Detail Changes

• Group by module / feature with subheadings, for example:
• ### Command / Management
• ### CPE Search Engine
• ### Normalization Logic
• ### Documentation
• For each subheading:
• List specific changes:
  • What functions / classes / commands were added (wrap in backticks)
  • Whether there are important parameters / defaults / weights (e.g., similarity score threshold, version weight)
  • Whether old logic was removed or certain behaviors deprecated
• No need to paste code, just let reviewers know "what changed and why they should care"

Step 4: Explain Behavior / Compatibility

• Clearly answer:
• Does this PR change existing external behavior (API response, CLI output, data format)?
• Is old version logic still maintained (e.g., v1 and v2 coexist, user chooses)?
• Are DB migrations / config file changes / new environment variables needed?
• If behavior differs, briefly explain "why the difference is expected and reasonable."

Style & Language

• Always use English (unless user specifically requests another language in conversation)
• Mark file names, class names, function names, CLI parameters with backticks (e.g., CPEQuery, search_cpes_v2, nist_cpe_handle_v2)
• Use bold to highlight keywords (e.g., behavioral changes, compatibility, performance)
• Avoid overly casual writing, but also don't need to write like academic papers, maintain the tone of everyday engineer PRs

What NOT to Do

• Do not when executing this Skill:
• Modify any code yourself
• Execute destructive shell commands (delete files, clear database, rebuild indexes, etc.)
• Fabricate changes or test results that didn't happen
• Do not paste entire large code blocks into PR descriptions, only describe logic and impact in text.

Example (High-Level Shape Only)

When actually producing, please base on the actual change content of the current branch, do not directly copy this example.

• ## Summary
• Added v2 query flow: Provides management command supporting full CPE 2.3 fields.
• Refactored CPE search logic: Encapsulates queries with CPEQuery, unifies normalization and scoring behavior.
• ... other sections filled according to guidelines.