/update-pr-description

name: update-pr-description
description: >
  Generate a PR description from the current branch's changes against a GitHub PR, using the gh CLI. Use when writing,
  drafting, or updating pull request descriptions, PR summaries, or PR bodies. Does not review code or post review
  comments — use code-review for local review or post-code-review-to-pr for posting a review to GitHub.
argument-hint: "[optional context about the PR]"
allowed-tools:
  Read, Glob, Grep, Agent, Bash(git *), Bash(gh *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Pre-requisites

• gh CLI: !`which gh 2>/dev/null || echo "not installed"`

**If the gh CLI is not found:**

• Inform the user that it needs to be installed and configured before this skill can be used
• **Immediately stop** execution of this skill, as it cannot be executed

Project Context

• current branch: !`git branch --show-current 2>/dev/null || echo unknown`
• default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`
• branch summary: !`git log origin/HEAD..HEAD --oneline 2>/dev/null || echo unknown`
• branch stats: !`git diff origin/HEAD...HEAD --stat 2>/dev/null || echo unknown`
• branch changes: !`git diff origin/HEAD...HEAD 2>/dev/null || echo unknown`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Step 1: Validate Branch State

Before generating a PR description, verify the branch has content to describe:

1. **If `default branch` is empty or `unknown`** — `origin/HEAD` is not set. Use `AskUserQuestion` to ask the user for the default branch name (e.g., `main`, `master`, `develop`). Use that branch as the base for all git commands in subsequent steps, and recompute `branch summary`, `branch stats`, and `branch changes` against it — their Project Context values may read `unknown` because they were derived from the unset `origin/HEAD`.

2. **If `branch summary` is empty** — there are no commits on this branch relative to the default branch. Inform the user and stop.

3. **If `branch stats` is empty** — there are no file changes despite having commits (e.g., empty commits or fully reverted changes). Inform the user and stop.

Step 2: Discover the Repository PR Template

Determine whether the repository defines its own GitHub pull-request template. If it does, the generated description must conform to that template's structure (Step 4). Do not assume any particular template shape — discover it, read it, and let its structure drive the output.

Use the `Glob` tool to look in GitHub's supported template locations. GitHub matches the filename case-insensitively; check both common casings since the working filesystem may be case-sensitive. Search these paths (most templates are `.md`; `.txt` is also valid):

• Root of the repo: `pull_request_template.md`, `PULL_REQUEST_TEMPLATE.md` (and the `.txt` variants).
• The `.github/` directory: `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md` (and `.txt`).
• The `docs/` directory: `docs/pull_request_template.md`, `docs/PULL_REQUEST_TEMPLATE.md` (and `.txt`).
• A multiple-template subdirectory: `.github/PULL_REQUEST_TEMPLATE/*.md`, `docs/PULL_REQUEST_TEMPLATE/*.md`,

`PULL_REQUEST_TEMPLATE/*.md`.

Then resolve to a single template (or none):

1. **No template file found** — the repository has no PR template. Record "no repository template" and continue. Step 4 uses the default structure. 2. **Exactly one single-file template found** — `Read` it in full, including HTML comments. Record its path and full contents. 3. **A `PULL_REQUEST_TEMPLATE/` directory with multiple templates** — GitHub selects one per PR and the skill cannot know which applies. Use `AskUserQuestion` to ask which template to conform to, listing the filenames plus a "None — use the default structure" option. `Read` the chosen file in full and record its path and contents. If the user picks "None," record "no repository template."

Carry the recorded result (the template path and full contents, or "no repository template") into Step 4. Preserve the template's HTML comments verbatim in what you carry forward — they often state how the template is meant to be used.

Step 3: Analyze Changes

Review the branch diff, commits, and relevant source code to understand the PR. Identify the central mechanism — the primary purpose of the PR. If the PR is about feature flags, migrations, or behavioral changes, those ARE the point, not a side detail. Classify the change type (new feature, bug fix, refactoring, docs update, config change, etc.) and read related source files as needed to understand the full scope.

Find the headline behavioral effect — what changes for a user or caller and why — and the central mechanism's key facts (a flag and its default, a migration's direction, the new vs. old behavior). Do not catalog every config value, phase, or mode; the diff carries the specifics. The goal is a short description, not an exhaustive one.

While analyzing, count the **significant** changed files from `branch stats`, since that count gates the "What to look at first" section in Step 4. "Significant" means code files. Documentation and configuration files do not count as significant by default; one counts only when there is explicit justification for how it changes the behavior of the code changes in the PR.

Step 4: Generate the PR