.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,72 @@
+<!--
+  PR title: Conventional Commits — type(scope): description
+    e.g. fix(mv): bring header and completions up to repo conventions
+    Lowercase after the colon, imperative mood, no trailing period.
+    Append `!` after the scope for a breaking change: feat(logging)!: ...
+    Types in use: feat, fix, docs, test, chore, perf, refactor, style.
+    See CONTRIBUTING.md § Commit Conventions.
+
+  Keep the two headings below, in this order, and delete these comments.
+  Optional sections may be added between them (see the note above
+  "Manual Verification").
+-->
+
+## Summary
+
+<!--
+  What changed and why. A short prose paragraph, 2-5 bullets, or a
+  paragraph followed by bullets — whichever fits the change.
+
+  - Name concrete paths and identifiers in backticks (`functions/mv.fish`,
+    `$__fish_config_op_autoexec`), not vague descriptions.
+  - Lead a bullet with a **bold phrase** when it covers a distinct file or
+    behavior, so the list scans at a glance.
+  - Explain the reasoning, not just the diff — a reader should understand
+    why this approach over the obvious alternative.
+  - Say so explicitly when there is no behavioral change, when a file is
+    generated by the docs pipeline, or when the change is scoped to the
+    site build only.
+-->
+
+<!--
+  OPTIONAL SECTIONS — add any `##` heading here that the change actually
+  needs, and skip them entirely for a straightforward one. Used in this
+  repo, roughly in order of frequency:
+
+    ## Root cause          — for a bug fix, what was actually wrong
+    ## Why                 — motivation, when it isn't obvious
+    ## How it works        — mechanism, for a non-trivial new feature
+    ## Behavior            — user-visible behavior before/after
+    ## Changes             — a longer breakdown than Summary can carry
+    ## Docs                — documentation touched by this change
+    ## Notes               — caveats, follow-ups, deferred work
+    ## Scope note          — what this deliberately does NOT cover
+    ## Opinionated guard (C1-C6)
+                           — which tier gates this, and behavior when off
+    ## ⚠️ Breaking Change  — required whenever the title carries `!`;
+                             state the break and the migration path
+
+  A "Why not <alternative>?" heading is also common when a reviewer would
+  reasonably ask why the obvious approach was rejected.
+-->
+
+## Manual Verification
+
+<!--
+  Reproducible steps a reviewer can run themselves, as a checkbox list.
+  Run them first, then check each box — an unchecked box means it was NOT
+  verified, and should be called out as such rather than left silently
+  blank. This section is always last.
+
+  - One check per line, imperative, with the exact command in backticks
+    and the expected result stated.
+  - Cover the regression path, not just the happy path: the old behavior
+    still working, the opinionated toggle disabled, the error branch.
+  - Include the repo's standing gates when the change touches what they
+    guard: `fish -n <file>`, `fish_indent`, `python3 docs/verify-manual.py`,
+    `python3 docs/build-manual.py --site`, `fish tests/run-tests.fish`.
+  - Reset any universal variable you set during a check.
+-->
+
+- [ ] 
+- [ ] 

CONTRIBUTING.md

@@ -64,6 +64,26 @@ assumes you *do* have push access (maintainers, regular contributors).
      approval before doing this** — there's no standing exception, no matter
      how trivial the change looks.
 
+### Pull request descriptions
+
+Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea and the GitHub mirror
+both pre-load it into the description box for you. Every PR carries, in
+this order:
+
+- **`## Summary`** — what changed and why, as a short paragraph, 2-5
+  bullets, or both. Name concrete paths and identifiers in backticks, and
+  explain the reasoning rather than restating the diff.
+- **Optional `##` sections** — add what the change actually needs
+  (`Root cause`, `Why`, `How it works`, `Behavior`, `Docs`, `Notes`,
+  `Scope note`, `Opinionated guard (C1-C6)`), and skip them entirely for a
+  straightforward change. A breaking change (title ending in `!` before
+  the colon) must include `## ⚠️ Breaking Change` with the migration path.
+- **`## Manual Verification`** — always last. Reproducible steps as a
+  checkbox list, each with the exact command and its expected result. Run
+  them before opening the PR and check the boxes; a box left unchecked
+  means that step was *not* verified, so say so explicitly rather than
+  leaving it silently blank.
+
 ## Commit Conventions
 
 Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):