# Copilot PR Description Instructions

When generating a pull request description for this repository, follow the
project's PR template at `.github/PULL_REQUEST_TEMPLATE.md` exactly.

## Required structure

The PR body MUST contain these five `##` sections, in this exact wording
(case-sensitive), in any order:

1. `## Why` -- 1-3 sentences on motivation. Include `Closes #N` or `Refs #N`
   when the PR resolves or relates to an issue.
2. `## What` -- bulleted list of changes in imperative voice. Avoid
   "this PR does X" filler.
3. `## How tested` -- commands run, scenarios verified. Manual smoke is
   acceptable when phrased explicitly.
4. `## Risk and rollback` -- what could break and how to revert.
5. `## CHANGELOG note` -- name the fragment the PR adds and paste its text
   (`changelog.d/<id>-<slug>.<kind>.md`, kind one of `added`, `changed`,
   `deprecated`, `removed`, `fixed`, `security`), or write
   `skip-changelog: <reason>` when the change does not touch a triggering
    path (`src/`, `pyproject.toml`, `packages/ui/`). Never edit `CHANGELOG.md`
    itself -- it is assembled from the fragments at release time.

Optionally append `## Agent metadata` for agent-authored PRs (single CC scope
declaration, single-goal confirmation, LOC declared, files-in-scope match).

## What NOT to do

- Do not invent extra sections (`## Summary`, `## TLDR`, `## Background` above
  `## Why`, etc.).
- Do not omit any required section.
- Do not use emoji.
- Do not include attribution footers (`Generated by Copilot`, `Co-authored-by:
  github-copilot[bot]`).
- Do not put body content inside HTML comments -- comments are stripped before
  validation.

## Validator behavior

CI workflow `pr-body / validate` fails the PR when any required section is
missing or empty. The only escape is the `trivial` label, reserved for
typo / comment / version-bump-only PRs.

## Schema source of truth

The canonical template is `.github/PULL_REQUEST_TEMPLATE.md`. If that file
changes, this instructions file must be updated to match. Maintainer
checklist: when updating either, update both.

## References

- `.github/PULL_REQUEST_TEMPLATE.md` -- canonical body schema
- `https://github.com/mcp-hangar/docs/blob/main/development/GIT_FLOW.md` -- full repo flow conventions
- `https://github.com/mcp-hangar/.github/blob/main/.github/workflows/pr-body.yml` -- validator implementation (reusable workflow)
