# Describe Pr

> Generate a PR description from the repo template, save it under flow/prs/, and update the live PR. Explicit-only; run only when invoked via /describe-pr or the user asks to describe a PR.

- Skill: `corticalstack/describe-pr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add corticalstack/describe-pr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/corticalstack/describe-pr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: corticalstack (https://skillmd.com/u/corticalstack)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/corticalstack/describe-pr

---


# Generate PR Description

You are tasked with generating a comprehensive pull request description following the repository's standard template.

## Steps to follow:

1. **Read the PR description template:**
   - Check if `.github/PULL_REQUEST_TEMPLATE.md` exists (standard GitHub location)
   - If it doesn't exist, use a standard PR template with Summary, Changes, Test Plan, and Checklist sections
   - Read the template carefully to understand all sections and requirements

2. **Identify the PR to describe:**
   - Check if the current branch has an associated PR: `tracker pr-current --json url,number,title,state 2>/dev/null`
   - If no PR exists for the current branch, or if on main/master, list open PRs: `tracker pr-list-open`
   - Ask the user which PR they want to describe

3. **Check for existing description:**
   - Check if `flow/prs/{number}_description.md` already exists
   - If it exists, read it and inform the user you'll be updating it
   - Consider what has changed since the last description was written

4. **Gather comprehensive PR information:**
   - Get the full PR diff: `tracker pr-diff {number}`
   - On GitHub: if you get an error about no default remote repository, instruct the user to run `gh repo set-default` and select the appropriate repository
   - Get commit history: `tracker pr-view {number} --json commits`
   - Review the base branch: `tracker pr-view {number} --json baseRefName`
   - Get PR metadata: `tracker pr-view {number} --json url,title,number,state`

5. **Analyze the changes thoroughly:** (ultrathink about the code changes, their architectural implications, and potential impacts)
   - Read through the entire diff carefully
   - For context, read any files that are referenced but not shown in the diff
   - Understand the purpose and impact of each change
   - Identify user-facing changes vs internal implementation details
   - Look for breaking changes or migration requirements

6. **Handle verification requirements:**
   - Look for any checklist items in the template
   - For each verification step:
     - If it's a command you can run (like `uv run pytest`, `npm test`, etc.), run it
     - If it passes, mark the checkbox as checked: `- [x]`
     - If it fails, keep it unchecked and note what failed: `- [ ]` with explanation
     - If it requires manual testing (UI interactions, external services), leave unchecked and note for user
   - Document any verification steps you couldn't complete

7. **Generate the description:**
   - Fill out each section from the template thoroughly:
     - Answer each question/section based on your analysis
     - Be specific about problems solved and changes made
     - Focus on user impact where relevant
     - Include technical details in appropriate sections
   - Ensure all checklist items are addressed (checked or explained)

8. **Save the description:**
   - Write the completed description to `flow/prs/{number}_description.md`
   - Show the user the generated description

9. **Update the PR:**
   - Update the PR description directly: `tracker pr-edit-body {number} flow/prs/{number}_description.md`
   - Confirm the update was successful
   - If any verification steps remain unchecked, remind the user to complete them before merging

10. **Transition linked work-item states** (if PR is linked to issues / work items):
    - Get linked work-item ids: `tracker pr-closing-issues {number}`
    - For each linked work item: `tracker set-state <id> pr-submitted in-progress`

## Important notes:
- This command works across different repositories - always read the local template
- Be thorough but concise - descriptions should be scannable
- Focus on the "why" as much as the "what"
- Include any breaking changes or migration notes prominently
- If the PR touches multiple components, organize the description accordingly
- Always attempt to run verification commands when possible
- Clearly communicate which verification steps need manual testing