update-pr-description

## 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 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.

This skill sources the standard by invoking `han-communication:readability-guidance` and applies it as it writes the PR
description, holding a named audience above the default: the reviewer