docs: write PR titles and descriptions for release notes

[jdx]

PR authors need to explain the final behavior clearly so users and release-note generators such as Communique can understand what changed. This adds guidance in AGENTS.md to keep titles and descriptions aligned with the final diff, lead with the user benefit, and include concrete examples or before/after behavior.

Screenshots and recordings are encouraged when useful, with captions and essential facts in text. The guidance also calls for relevant requirements and migration steps, measured performance claims, and proportionate validation. A usage-specific hypothetical example shows the expected style; small fixes can stay short.

Validation: git diff --check and review of the added guidance; Prettier on AGENTS.md. Documentation-only change.

AI-assisted — Tool: Codex; model: openai/unavailable; version: unavailable.

---

Note

Low Risk
Documentation-only change to contributor/agent guidance in AGENTS.md with no effect on product code or releases beyond how PRs are written.

Overview
Adds a new PR titles and descriptions are release-note inputs section to AGENTS.md, aimed at coding agents and contributors whose PR text feeds release notes (including Communique).

The guidance requires titles and bodies to match the final diff, lead with user-visible outcomes in conventional-commit titles, and include concrete examples or before/after behavior where it helps. It also covers captions and text-only facts for screenshots, adoption/migration details when relevant, measured performance claims, and keeping validation notes proportionate—plus a usage-style hypothetical (fix(zsh): complete values containing spaces) instead of vague titles like “address review feedback.” The section explicitly supplements existing commit, release, and disclosure rules; no runtime or CLI behavior changes.

^{Reviewed by Cursor Bugbot for commit f5b067f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added guidance for writing pull request titles and descriptions as release-note source material.
  • Guidance emphasizes user-visible outcomes, concrete examples, essential details, adoption information, and appropriately scoped review context.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Advanced

Run ID: 88de8198-b23e-4c39-82f6-dbc5790c86c2

📥 Commits

Reviewing files that changed from the base of the PR and between 56cf823 and f5b067f.

📒 Files selected for processing (1)

• AGENTS.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Added an AGENTS.md section that guides agents to write PR titles and descriptions as release-note source material.

Changes

Release-note writing guidance

Layer / File(s)	Summary
PR title and description guidance AGENTS.md	Added guidance to describe final results, lead with user-visible changes, provide examples, include essential facts, state adoption details, and keep review details proportionate.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to f5b06

This documentation-only change is ready to merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding documentation guidance for writing PR titles and descriptions as release-note inputs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

This documentation-only change appears safe to merge.

Summary

• Requires titles and descriptions to reflect the final diff.
• Encourages concrete examples, measured claims, adoption details, and proportionate validation.
• Preserves existing commit, release, and disclosure requirements.

_{Reviews (1) · Last reviewed commit: "docs: write PR titles and descriptions f..."}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▅▅▅████▁▁▁▁	384,244,096 → 384,149,349	-0.02%	64.22 → 64.40ms	+0.28%
startup	▁▁▁█▄▄▄▄▄▃▄	981,111 → 988,103	+0.71%	1.35 → 1.36ms	+0.40%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	stripped binary, bytes
usage	1349840
bpaf	2493216
clap	3101656

framework	instructions, cold parse	vs usage
usage	8607	—
clap	6314655	733x
bpaf	21909025	2545x

                                              min       p01       p10    median
usage-rs: argv -> struct                      763       765       766       771  ns
clap: build tree + parse -> struct        1228392   1234683   1242786   1257738  ns
bpaf: build parser + parse -> struct      3402472   3402472   3471736   3511392  ns

usage: argv -> struct                             790 ns      0.79 µs
clap: build tree + parse -> struct            1263695 ns   1263.69 µs
clap: parse -> struct, tree reused              50493 ns     50.49 µs
clap: build tree only                          757444 ns    757.44 µs

_{f5b067f404e9 vs 56cf8235b0e0 · measured on the runner, not pushed to the history.}