Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

chore(agents): PR descriptions - require diff size justification (#2032)

Andrew Barba4aba60852f0a
diff --git a/.agents/skills/gh-pr-description/SKILL.md b/.agents/skills/gh-pr-description/SKILL.md
index d909c4ee8..082203b0d 100644
--- a/.agents/skills/gh-pr-description/SKILL.md
+++ b/.agents/skills/gh-pr-description/SKILL.md
@@ -21,7 +21,80 @@ Fill in the repository template. Write for a reviewer:
- link the prior issue with `Closes #N`, `Related to #N`, or equivalent
- scale length with risk, not diff size
-Default to the shortest body that answers the four questions below. Keep the
+Append a `### Diff size` section after the template checklist. This must be the
+last section of every PR description and must account for every changed file in
+exactly one of these categories:
+
+- **Docs** — documentation, research, changesets, and other prose or release
+ metadata
+- **Implementation** — product code, configuration, dependencies, build files,
+ and generated runtime artifacts
+- **Tests** — tests, evals, test-only fixtures, and snapshots
+
+Use three full-width category blocks in the order above, including categories
+with no changes. Do not use a table: the overview and any reviewer-relevant
+context need the full description width to remain readable on GitHub.
+
+```markdown
+### Diff size
+
+**Docs** — 0 files · `+0 / -0`
+
+Not applicable.
+
+**Implementation** — 1 file · `+12 / -4`
+
+Focused implementation of the behavior above.
+
+**Tests** — 1 file · `+28 / -0`
+
+Regression coverage for success and failure paths.
+```
+
+Keep each category's file count, additions, and deletions visible on its bold
+heading line. Treat the section as an overview, not a file inventory: do not
+list every changed path. Mention individual files only when they are critical
+to understanding or reviewing the change, under a short `Key files` list. Omit
+paths entirely when no file needs special attention. The category counts must
+still include every changed file. Do not collapse the category totals or the
+entire Diff size section.
+
+Report additions and deletions from the full branch diff against the PR base,
+and verify that the three categories reconcile with the complete diff. Note
+binary files separately instead of treating them as zero-line changes. Classify
+a mixed-purpose file by its primary purpose; mention that ambiguity only when it
+is useful to the reviewer.
+
+The justification must explain why each category needs that amount of change,
+not merely restate its line count. Call out a file or category only when its
+size is genuinely surprising or materially disproportionate to the behavior
+and review scope, especially for generated files, snapshots, fixtures, or
+mechanical changes. Being the only changed file, the largest category, or a
+modest one-file diff does not make something an outlier.
+
+Keep a concise explanation visible. If supporting detail would be lengthy, use
+a category-local `<details>` block with a specific, natural summary such as
+`Generated output`, `Fixture expansion`, or `Mechanical migration`; do not use
+a prescribed heading or force words such as `unusually`. Explain why the large
+portion is necessary and could not reasonably be smaller. If the size is
+surprising for the stated behavior, flag it for reviewer attention rather than
+normalizing it. Do not manufacture an outlier explanation for an ordinary diff.
+The rest of the description should still discuss behavior rather than enumerate
+files; this section is the required exception.
+
+```markdown
+Generated output accounts for most of the implementation diff.
+
+<details>
+<summary>Generated output</summary>
+
+Explain why the generated changes are necessary and could not reasonably be
+smaller.
+
+</details>
+```
+
+Default to the shortest body that answers the five 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
@@ -44,6 +117,20 @@ the compiler now treats missing optional directories as empty.
### Checklist
(preserved from the template; only verified items checked)
+
+### Diff size
+
+**Docs** — 0 files · `+0 / -0`
+
+Not applicable.
+
+**Implementation** — 1 file · `+6 / -2`
+
+Keeps the missing-directory handling local to the compiler.
+
+**Tests** — 1 file · `+14 / -0`
+
+Covers the regression without broad fixture changes.
```
Under validation, list exact checks actually run and useful manual coverage. State
@@ -59,10 +146,12 @@ Before returning or publishing the description, confirm that it answers:
2. What meaningfully changes?
3. How was it validated?
4. What should the reviewer pay special attention to?
+5. How is the complete diff divided among docs, implementation, and tests, and
+ why is each category that size?
-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.
+Then prune: outside the required Diff size section, 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`.