docs: write PR titles and descriptions for release notes

AGENTS.md

@@ -234,6 +234,47 @@ allowance — stop and ask instead of doing it.
 - `tera`: Template engine for markdown docs
 - `insta`: Snapshot testing
 
+## PR titles and descriptions are release-note inputs
+
+PR titles and descriptions are source material for release notes, including those
+generated by Communique. Write them for a usage user who has not read the diff
+or this conversation.
+
+- **Describe the final result.** Before requesting review and again after feedback
+  changes the implementation, compare the title and body with the complete current
+  diff. Rewrite both when the scope changes. Remove abandoned approaches, stale
+  requirements, and claims that the final code or validation no longer supports.
+- **Lead with the user-visible change.** Keep the conventional commit format, but
+  name the affected behavior and outcome in the title. Open the body with the
+  problem or use case and what users can now do. Avoid titles such as "address
+  feedback" or "fix CI" when the PR's actual purpose is a feature or behavior fix.
+  For internal-only work, explain the concrete maintainer or contributor benefit
+  without inventing a user-facing impact.
+- **Make the change concrete.** For new configuration, commands, or APIs, include
+  a small, valid example and explain its result. For a bug fix, describe the trigger
+  and before/after behavior. For visible UI or output changes, include actual
+  before/after screenshots or a short recording when they help reviewers assess the
+  change; CLI input/output snippets are often clearer than terminal screenshots.
+  Use measured results for performance claims and state how they were measured.
+- **Keep the essential facts in text.** Caption screenshots and explain examples.
+  A reader or release-note generator should understand the change without opening
+  an image, following an external link, or reading the diff. Do not fabricate
+  screenshots, output, measurements, or validation results.
+- **State adoption details when relevant.** Include new flags or settings, defaults,
+  supported platforms, experimental status, required dependency versions, and any
+  compatibility changes or migration steps that affect using the feature. Distinguish
+  current behavior from planned follow-ups; do not advertise unfinished work.
+- **Keep review details proportionate.** Summarize meaningful validation and its
+  limitations. Include implementation details only when they explain behavior or a
+  tradeoff reviewers need to assess. Omit agent work logs, intermediate commit
+  summaries, and exhaustive test-command lists. A small fix can be a short paragraph
+  and a test result; screenshots and sections are not mandatory for every PR.
+
+For a hypothetical fix, prefer `fix(zsh): complete values containing spaces`
+over `fix: address review feedback`. Its description should show the relevant spec and completion input, then explain the candidates the shell now receives.
+These rules supplement the repository's existing commit, release, and disclosure
+requirements.
+
 ## GitHub Interactions
 
 When posting comments on GitHub PRs or discussions, always include a note that the comment was AI-generated (e.g., "_This comment was generated by Claude Code._").