Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

chore: enforce concise PR descriptions in gh-pr-description skill (#1782)

Chad Hietala3f22989669f8
diff --git a/.agents/skills/gh-pr-description/SKILL.md b/.agents/skills/gh-pr-description/SKILL.md
index 3cc3efc5c..d909c4ee8 100644
--- a/.agents/skills/gh-pr-description/SKILL.md
+++ b/.agents/skills/gh-pr-description/SKILL.md
@@ -6,7 +6,7 @@ description: Drafts and reviews GitHub pull request descriptions for the eve rep
# GitHub PR description
See [review notes](references/review-notes.md) for the maintainer patterns behind
-this workflow.
+this workflow; they describe what to cover, not how much to write.
Read `CONTRIBUTING.md` and `.github/pull_request_template.md`, then inspect the
branch diff, commits, related issue, tests, docs, and changesets. If updating a
@@ -19,21 +19,39 @@ Fill in the repository template. Write for a reviewer:
- 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
+- scale length with risk, not diff size
-Keep the description concise and reviewer-focused. Prefer plain language; omit
-unnecessary implementation detail and technical jargon, but include either when
-needed to understand behavior, risk, scope, or a non-obvious decision. Do not
-restate the issue, template guidance, or checklist. For a small, low-risk
-change, prefer a single Summary sentence; use bullets only when they improve
-clarity.
+Default to the shortest body that answers the four questions below. Keep the
+Summary under 5 sentences for most PRs; exceed 10 lines only for breaking or
+cross-cutting changes. Prefer plain language. Include implementation detail or
+jargon only when the reviewer cannot assess behavior or risk without it. Do not
+restate the issue, template guidance, or checklist. Use bullets only when they
+improve clarity.
+
+A typical small PR body:
+
+```markdown
+### Summary
+
+Closes #412. `eve dev` crashed when an agent had no `connections/` directory;
+the compiler now treats missing optional directories as empty.
+
+### Validation
+
+- Reproduced the crash with the weather fixture, then confirmed a clean boot
+- `pnpm test:unit`, `pnpm typecheck`
+
+### Checklist
+
+(preserved from the template; only verified items checked)
+```
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.
+Preserve the checklist and check only verified items. If tests, docs, or a
+changeset are not applicable, say so in one short line at most.
Before returning or publishing the description, confirm that it answers:
@@ -42,5 +60,9 @@ Before returning or publishing the description, confirm that it answers:
3. How was it validated?
4. What should the reviewer pay special attention to?
+Then prune: delete any sentence that restates the diff, the issue, or the
+template, and any detail the reviewer does not need. If the answer to question
+4 is "nothing," leave it out.
+
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`.