The Open Framework for Building Agents
chore: add shared PR description guidance (#1642)
Colton Padden570e82513b67
diff --git a/.agents/skills/gh-pr-description/SKILL.md b/.agents/skills/gh-pr-description/SKILL.mdnew file mode 100644index 000000000..331a012ad--- /dev/null+++ b/.agents/skills/gh-pr-description/SKILL.md@@ -0,0 +1,39 @@+---+name: gh-pr-description+description: Drafts and reviews GitHub pull request descriptions for the eve repository. Use when opening, updating, or reviewing a PR, or when summarizing a branch for reviewers.+---++# GitHub PR description++See [review notes](references/review-notes.md) for the maintainer patterns behind+this workflow.++Read `CONTRIBUTING.md` and `.github/pull_request_template.md`, then inspect the+branch diff, commits, related issue, tests, docs, and changesets. If updating a+PR, read its current body too.++Fill in the repository template. Write for a reviewer:++- explain the concrete problem and solution near the top+- summarize meaningful behavior and decisions, not files or commits+- mention breaking changes, preserved behavior, scope boundaries, or stacked+ PRs only when relevant+- link the prior issue with `Closes #N`, `Related to #N`, or equivalent+- keep the detail proportional to the change++Under validation, list exact checks actually run and useful manual coverage. State+limitations honestly. Do not infer results or claim checks that only CI will+run.++Preserve the checklist and check only verified items. Explain when tests, docs,+or a changeset are not applicable.++Before returning or publishing the description, confirm that it answers:++1. What problem does this solve?+2. What meaningfully changes?+3. How was it validated?+4. What should the reviewer pay special attention to?++When asked only to draft, return the body for review. When asked to create or+update the PR, pass a body file to `gh pr create` or `gh pr edit`.diff --git a/.agents/skills/gh-pr-description/references/review-notes.md b/.agents/skills/gh-pr-description/references/review-notes.mdnew file mode 100644index 000000000..cb5ad0e90--- /dev/null+++ b/.agents/skills/gh-pr-description/references/review-notes.md@@ -0,0 +1,31 @@+# PR description review notes++These guidelines were derived from the five most recent pull request+descriptions by Casey Gowrie and Andrew Barba, together with the repository's+contributing guidelines and pull request template.++## What made the descriptions useful++- **They led with outcomes.** Short summaries made the problem and resulting+ behavior clear before implementation details.+- **They emphasized review-significant details.** Bullets covered public+ behavior, contracts, design decisions, and regression coverage rather than+ listing changed files.+- **They named boundaries.** Larger changes identified preserved behavior,+ deliberate non-goals, compatibility implications, and where work belonged in+ a stack of changes.+- **They provided context.** Descriptions identified the related issue or+ proposal and distinguished closing, related, superseded, and dependent work.+- **They gave concrete validation.** Test sections named exact commands,+ focused suites, pass counts, and manual checks where useful.+- **They were candid about limitations.** When local validation was blocked,+ the description said why and what CI would cover instead.+- **They scaled with risk.** Small fixes used a few bullets; broad or breaking+ changes included enough structure to explain scope and migration impact.+- **They accounted for repository obligations.** Tests, documentation,+ changesets, and cases where those were not applicable were made explicit.++The resulting standard is reviewer-oriented: explain the problem, meaningful+change, validation, and anything that deserves special attention. Avoid file+inventories, commit narration, unsupported claims, and boilerplate that does+not help review.diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex a24fadd07..322581fbc 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -1,12 +1,20 @@-### Description+### Summary-<!-- Write a short summary of the problem and solution. -->+<!--+Link the issue where this change was discussed (for example, "Closes #123" or+"Related to #123"). Explain the concrete problem and solution, then summarize+meaningful behavior or decisions—not changed files or commits. Call out breaking+changes, preserved behavior, scope boundaries, or stacked PRs when relevant.+-->-### How did you test your changes?+### Validation-<!-- Include the commands you ran and any manual coverage. -->+<!--+List the exact commands you ran and useful manual coverage. Include relevant+results or limitations. Explain when tests are not applicable.+-->-### PR Checklist+### Checklist- [ ] I linked an issue with prior discussion confirming this change is wanted- [ ] I ran the relevant checks from `CONTRIBUTING.md`diff --git a/AGENTS.md b/AGENTS.mdindex 6418ab59e..1393321ab 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -31,6 +31,13 @@ the DCO `Signed-off-by` trailer. Use `git commit -s` for every commit, and if acommit is missing the trailer, amend it with `git commit --amend -s --no-edit`before pushing.+PR descriptions are reviewer-oriented explanations of the problem, solution,+meaningful behavior changes, and validation—not file lists or commit logs. Keep+them proportional to the change, link the prior issue, call out important scope+boundaries or preserved behavior, and report only checks actually run. Use the+[`gh-pr-description`](./.agents/skills/gh-pr-description/SKILL.md) skill when+drafting or updating one.+## Commands```sh