update-pr-description

## Pre-requisites

- gh CLI: !`which gh`

**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`
- default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD`
- branch summary: !`git log origin/HEAD..HEAD --oneline`
- branch stats: !`git diff origin/HEAD...HEAD --stat`
- branch changes: !`git diff origin/HEAD...HEAD`

## Step 1: Validate Branch State

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

1. **If `default branch` is empty** — `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.

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 Description

Launch a single `han-core:junior-developer` agent to write the PR description directly. Junior-developer's fresh-reviewer perspective is the asset here: by authoring the description with the eyes of a teammate who lacks full project context, the result already anticipates what a reviewer needs to see, removing the need for a separate reviewer-context edit pass.

First, compose the **structure directive** based on the Step 2 result. The structure directive is the only part of the prompt that differs between the two cases; everything else is shared.

- **Option A — no repository template** (Step 2 recorded "no repository template"). The structure directive is:
  > **Structure (required):** Produce the description using this fixed structure and section order: Summary (the bolded TL;DR sentence only) → Behavior changes (its own `##` section, present only when runtime behavior changes; omit for pure refactors and docs-only PRs) → What to look at first (only when the PR has more than ~8-10 files with significant changes; see the threshold rule below). The first line under `## Summary` MUST be the bolded TL;DR sentence, and the Summary section contains nothing else — no bullet list, no file mentions. Include the `## Behavior changes` section only when runtime behavior changes (flag flips, migrations, state-machine edits, config changes, API contract changes); omit it for pure refactors and docs-only PRs.
  >
  > **Length (required):** The whole description is at most 2-5 short paragraphs (the Summary sentence is one of them), and Behavior changes is 1-3 short paragraphs. A small table is fine