Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.md
index 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 a
commit 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