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 5). 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 5 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 5. 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.

When applicable (do not force these into every PR), collect specific details: feature flag gate names/values/interactions, actual config values per environment, before/after behavioral changes, migration phases/rollback/data flow, and state machine combinations.

## Step 4: Determine "How this was tested" Applicability

Inspect the changed files from `branch stats` and classify each by extension. Documentation files: `.md`, `.txt`, `.rst`, `.adoc`, `.rdoc`, `.textile`, `.wiki`, `.org`, `.asciidoc`, `.creole`, `.pod`, `.mediawiki`. Everything else is a code or configuration file. If ALL changed files are documentation → omit the "How this was tested" section. If ANY changed file is code or configuration → include the "How this was tested" section.

## Step 5: 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 (with a `### Behavior changes` subsection only when runtime behavior changes) → What to look at first → How this was tested (only when included per the inclusion decision) → Files of interest → Test scenario changes (only if tests were added or edited). The first line under `## Summary` MUST be the bolded TL;DR sentence, before anything else is drafted. Include the `### Behavior changes` subsection 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; render interacting flags or modes as a small table.
  >
  > Default template to follow:
  > {paste the contents of [template.md](./references/template.md)}

- **Option B — a repository template was found** (Step 2 recorded