pr-description ยท diff
git:20260914.fe83353 to git:20261027.bb870bd
45 added, 4 removed. Audit A to A.
---
name: pr-description
- description: Calculate and maintain the required change-count header when creating or updating pull requests in this repository.
+ description: Write and maintain pull request descriptions in this repository, including the required change-count header, the before-and-after section, and screenshots or recordings for visible changes.
---
# PR description
+ Use the section order in `.github/pull_request_template.md`: change-count header,
+ What, Why, Before / After, How, Testing, Checklist. Preserve the rest of an existing
+ PR description when updating it.
+
+ ## Change-count header
+
Begin every PR description with these three lines, using Markdown hard line breaks
so each renders separately:
```text
Code changes: +<added> -<deleted>
Tests: +<added> -<deleted>
Others: +<added> -<deleted>
```
Calculate the numbers from the net diff against the PR's actual base. For a local
branch, use `git diff --numstat <base>...<head>`. After pushing, prefer GitHub's
per-file additions and deletions. Recalculate after the final push rather than
summing commit churn or estimating counts.
Count every changed file exactly once:
- **Code changes:** handwritten implementation, including SQL, migrations, styles,
and executable scripts.
- **Tests:** test code, fixtures, snapshots, and test-only helpers.
- **Others:** generated or vendored files, lockfiles, documentation, configuration,
and assets. Generated output belongs here even when it contains source code.
Show `+0 -0` for empty categories. Binary files have no line count; mention their
count separately when present. Add a brief qualifier when useful, such as
`Others: +11 -0 (generated sqlc)`.
- Preserve the rest of an existing PR description. After creating or updating the PR,
- read the published description and verify that its opening lines match the current
- GitHub diff counts and required order.
+ ## Before / After
+
+ Every PR has a `## Before / After` section with a two-column table, one row per
+ behavior that changed:
+
+ ```markdown
+ | Before | After |
+ | --- | --- |
+ |  |  |
+ | `ao session ls` exits 1 when a project has no sessions | Prints `No sessions` and exits 0 |
+ ```
+
+ - **UI changes** need a screenshot of each changed state, before and after. Use a
+ short recording for flows, animations, focus or keyboard behavior, and timing.
+ - **Non-visual changes** compare observable behavior: command output, API
+ responses, errors, logs, or measured numbers with their units.
+ - **No user-visible change:** write `No user-visible change` and one line saying why,
+ such as an internal refactor or a test-only change.
+
+ Capture both sides from the real app with the same screen, window size, and data,
+ so they compare directly. Take the before capture from the PR's base branch. The
+ `ao-desktop-dev` skill launches the desktop app from a checkout.
+
+ Screenshots and GIFs go in the table. GitHub renders a video player only for a
+ bare attachment URL on its own line, so put MP4 or MOV recordings on their own
+ line below the table, with one line saying what they show.
+
+ Never commit screenshots or recordings to the repository. Attach them in the PR
+ description, or in a PR comment when the description gets long. If you cannot
+ upload, give the capture file paths to the person who will attach them. Remove
+ secrets, tokens, and personal data from every capture.
+
+ ## Verify
+
+ After creating or updating the PR, read the published description and verify that:
+
+ - its opening lines match the current GitHub diff counts and required order;
+ - every image and recording in Before / After, or in a PR comment, loads.