From 55c9a2fdebcc7da1ad73abc677f37d5125fb4787 Mon Sep 17 00:00:00 2001 From: BenSheridanEdwards Date: Mon, 22 Jun 2026 05:16:02 +0100 Subject: [PATCH 1/2] Add PR quality contract --- .agents/definition_of_done.md | 41 +++++++++++++++++++++ .agents/skills/pr-quality-contract/SKILL.md | 23 ++++++++++++ .github/pull_request_template.md | 21 +++++++++++ 3 files changed, 85 insertions(+) create mode 100644 .agents/definition_of_done.md create mode 100644 .agents/skills/pr-quality-contract/SKILL.md create mode 100644 .github/pull_request_template.md diff --git a/.agents/definition_of_done.md b/.agents/definition_of_done.md new file mode 100644 index 0000000..b90e20e --- /dev/null +++ b/.agents/definition_of_done.md @@ -0,0 +1,41 @@ +# Definition of Done + +A completed PR must contain the items below. If an item does not apply, the PR must state `Not applicable` and give the technical reason. + +## Required PR Body + +The PR body must use `.github/pull_request_template.md` and preserve these sections in this order: + +1. `Why does this feature exist?` +2. `What changed?` +3. `Behavioural Proof (with video and screenshots)` +4. `Verification Summary` + +## Scope and Implementation + +- The reason for the change is stated in user, product, or technical terms. +- The changed files and behavior are summarized precisely. +- The implementation avoids unrelated refactors, formatting churn, and hidden scope expansion. +- New configuration, migrations, permissions, dependencies, or public API changes are called out. + +## Behavioural Proof + +- UI behavior changes include screenshots from the branch under review. +- Flows with motion, timing, cursor behavior, audio, or multi-step interaction include video when practical. +- Screenshots and videos must show the changed behavior, not a generic happy path. +- Behaviour/E2E tests map to the user-visible behavior changed by the PR. +- Missing visual proof or E2E coverage is allowed only with a technical reason and a stated replacement verification method. + +## Verification + +- Format, lint, typecheck, unit, integration, and E2E checks relevant to the changed files are run after the final code change. +- Test command names and pass/fail results are listed in the PR. +- Existing unrelated failures are separated from failures introduced by the PR. +- Any skipped check includes the reason, risk, and owner for follow-up. + +## Review Readiness + +- Documentation is updated when behavior, setup, or operation changes. +- Security, privacy, data retention, accessibility, and performance effects are considered when relevant. +- The PR does not contain secrets, local-only paths, generated junk, or unrelated artifacts. +- The branch is ready for review only when the PR body contains concrete evidence, not placeholders. diff --git a/.agents/skills/pr-quality-contract/SKILL.md b/.agents/skills/pr-quality-contract/SKILL.md new file mode 100644 index 0000000..3428915 --- /dev/null +++ b/.agents/skills/pr-quality-contract/SKILL.md @@ -0,0 +1,23 @@ +--- +name: pr-quality-contract +description: Use before completing work or opening a PR in this repository. +--- + +# PR Quality Contract + +## Steps + +1. Read `.agents/definition_of_done.md` before implementation starts. Completion criterion: the PR scope, required proof, and verification commands are known before coding. +2. Map behavior changes to tests. Completion criterion: every user-visible behavior changed by the PR has an automated behavior/E2E test or an explicit technical reason it cannot be automated. +3. Produce behavioral proof for UI changes. Completion criterion: the PR contains current video and screenshots from the changed branch, or states `Not applicable` with the reason. +4. Run verification on the final branch. Completion criterion: format/lint/type/test/E2E commands relevant to the changed files have been run after the last code change. +5. Write the PR body using `.github/pull_request_template.md` exactly. Completion criterion: the PR body contains, in order, `Why does this feature exist?`, `What changed?`, `Behavioural Proof (with video and screenshots)`, and `Verification Summary`. +6. Do not mark work complete with placeholders. Completion criterion: every proof link, screenshot path, video path, test command, failure, skipped check, and residual risk is explicit. + +## Evidence Rules + +- Test claims require command output. +- UI behavior claims require screenshots or video from the branch under review. +- E2E claims require named scenarios and their pass/fail result. +- Skipped proof requires a technical reason, not convenience. +- Existing unrelated failures must be separated from failures introduced by the PR. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f0a458a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +# Why does this feature exist? + +- + +# What changed? + +- + +# Behavioural Proof (with video and screenshots) + +- Video: +- Screenshots: +- Behaviour tests: +- E2E mapping: + +# Verification Summary + +- Definition of Done: +- Commands run: +- Results: +- Known risks or skipped checks: From 9ffc2ab47de55af202357780af5f326ebadb4768 Mon Sep 17 00:00:00 2001 From: BenSheridanEdwards Date: Mon, 22 Jun 2026 05:17:57 +0100 Subject: [PATCH 2/2] Add PR quality contract --- .github/pull_request_template.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f0a458a..034997c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,21 +1,21 @@ # Why does this feature exist? -- +- # What changed? -- +- # Behavioural Proof (with video and screenshots) -- Video: -- Screenshots: -- Behaviour tests: -- E2E mapping: +- Video: +- Screenshots: +- Behaviour tests: +- E2E mapping: # Verification Summary -- Definition of Done: -- Commands run: -- Results: -- Known risks or skipped checks: +- Definition of Done: +- Commands run: +- Results: +- Known risks or skipped checks: