From ff70bda6c01ed1ec334019dd5af35c2416c1c7ff Mon Sep 17 00:00:00 2001 From: bonaventure001 Date: Wed, 29 Jul 2026 07:38:59 +0100 Subject: [PATCH] docs: add acceptance criteria audit template - Add docs/acceptance-criteria-audit-template.md: a per-criterion evidence table (Criterion / Evidence / Status) replacing the flat checkbox list, with Done/Partial/Deferred/N/A statuses and rules for handling incomplete criteria (Relates to #N, not Closes #N) - Update PR template Section 6 to use the audit table instead of checkboxes - Update CONTRIBUTING.md and docs/pr-evidence-checklist.md to reference the new template Relates to #116 --- .github/PULL_REQUEST_TEMPLATE.md | 13 +-- CONTRIBUTING.md | 4 +- docs/acceptance-criteria-audit-template.md | 98 ++++++++++++++++++++++ docs/pr-evidence-checklist.md | 11 +-- 4 files changed, 114 insertions(+), 12 deletions(-) create mode 100644 docs/acceptance-criteria-audit-template.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 39a6246..f89e25a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -76,14 +76,15 @@ npm run check -### 6. Acceptance Criteria Coverage +### 6. Acceptance Criteria Audit -Copy the acceptance criteria from the linked issue and check off each item -that this PR satisfies. +Fill in one row per criterion from the linked issue using the +[Acceptance Criteria Audit Template](../docs/acceptance-criteria-audit-template.md). +Do not mark a criterion Done without evidence in its row. -- [ ] -- [ ] -- [ ] +| Criterion | Evidence | Status | +|---|---|---| +| | | | --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7991ccf..1113524 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,9 @@ every submission includes: 3. **Tests** — new or updated tests (or a written justification if not applicable). 4. **Commands run** — pasted terminal output proving local verification passed. 5. **CI status** — confirmation that all GitHub Actions checks are green. -6. **Acceptance criteria coverage** — each criterion from the issue checked off. +6. **Acceptance criteria audit** — each criterion from the issue mapped to + evidence and a status, using the + [Acceptance Criteria Audit Template](docs/acceptance-criteria-audit-template.md). For detailed guidance on each item, see [`docs/pr-evidence-checklist.md`](docs/pr-evidence-checklist.md). diff --git a/docs/acceptance-criteria-audit-template.md b/docs/acceptance-criteria-audit-template.md new file mode 100644 index 0000000..dc54dee --- /dev/null +++ b/docs/acceptance-criteria-audit-template.md @@ -0,0 +1,98 @@ +# Acceptance Criteria Audit Template + +## Status + +**Applies to:** Aegis SDK (`@aegis/sdk`) +**Companion to:** [Pull Request Evidence Checklist](./pr-evidence-checklist.md), Section 6 + +--- + +## Purpose + +Section 6 of the [PR Evidence Checklist](./pr-evidence-checklist.md#6-acceptance-criteria-coverage) +requires every acceptance criterion from the linked issue to be addressed. A +plain checked-off list makes it easy to mark a criterion done without +showing *how*. This template replaces the checklist with a per-criterion +audit row, so a reviewer can verify completeness without re-reading the +whole diff. + +--- + +## How to use this template + +For each acceptance criterion in the linked issue, copy the criterion text +verbatim and fill in one row. Do not merge two criteria into one row, even +if a single change satisfies both -- reviewers check rows against the issue +one at a time. + +| Criterion | Evidence | Status | +|---|---|---| +| *(copied verbatim from the issue)* | *(file/diff/test that satisfies it)* | *(see status values below)* | + +| Requirement | Every row must show implementation evidence, and test or documentation evidence where applicable. | +|---|---| +| **Why** | A criterion marked "done" with no evidence is unverifiable -- the reviewer either re-derives it from the diff themselves or takes it on faith. Neither scales. | +| **How to satisfy** | Point to something concrete: a file path and symbol name, a test name plus the command that runs it, or a doc section. If none of those apply, say why in the evidence cell rather than leaving it blank. | +| **Acceptable evidence** | `src/client.ts` exports `X` -- not "implemented client changes." `tests/client.test.ts::handles timeout` -- not "added tests." | + +--- + +## Status values + +| Status | Meaning | +|---|---| +| **Done** | Criterion is fully implemented and its evidence is verifiable in this PR. | +| **Partial** | Some but not all of the criterion is addressed in this PR. | +| **Deferred** | Intentionally out of scope for this PR; requires a follow-up. | +| **N/A** | Criterion does not apply to this change -- explain why in the evidence cell. | + +A criterion should not be marked **Done** if its evidence cell is empty or +vague. If you are unsure whether something counts as sufficient evidence, +under-claim (mark **Partial**) rather than over-claim. + +--- + +## Handling incomplete criteria + +If any row is **Partial** or **Deferred**: + +1. The PR description must use `Relates to #N`, not `Closes #N` or `Fixes #N`. +2. The evidence cell for that row states what remains. +3. If a follow-up issue already exists, link it. If not, say so explicitly + so a maintainer can decide whether to open one -- don't silently drop it. + +A PR should never claim an issue is fully resolved (`Closes #N`) while any +row in its own audit table says otherwise. + +--- + +## Worked example + +Issue acceptance criteria: +- Add retry logic to `fetchBalance`. +- Document the retry behaviour. + +Audit: + +| Criterion | Evidence | Status | +|---|---|---| +| Add retry logic to `fetchBalance`. | `src/client.ts`: `fetchBalance` now retries up to 3 times on `NetworkError`; see `tests/client.test.ts::retries on network error`. | Done | +| Document the retry behaviour. | `docs/network-failures.md` section "Retry policy" describes the 3-attempt backoff. | Done | + +If retry logic had been added without updating the docs criterion, that +second row would read: + +| Criterion | Evidence | Status | +|---|---|---| +| Document the retry behaviour. | Not yet written; tracking in follow-up. | Deferred | + +-- and the PR description would say `Relates to #N`, not `Closes #N`. + +--- + +## Related Documentation + +- [Pull Request Evidence Checklist](./pr-evidence-checklist.md) -- the full + six-item PR requirement list this template supports. +- [Contributing Guide](../CONTRIBUTING.md) -- development workflow and PR + process. diff --git a/docs/pr-evidence-checklist.md b/docs/pr-evidence-checklist.md index 6ea6684..5644449 100644 --- a/docs/pr-evidence-checklist.md +++ b/docs/pr-evidence-checklist.md @@ -119,16 +119,17 @@ reviewer notes section so reviewers do not attribute them to your PR. | Requirement | Every acceptance criterion from the linked issue must be addressed. | |---|---| | **Why** | PRs that miss acceptance criteria create incomplete issues that are hard to track and re-open. | -| **How to satisfy** | Copy each acceptance criterion from the issue into the PR template's Section 6. Check off each item and briefly note how it is satisfied (a file path, a test name, or a sentence). | -| **Acceptable evidence** | A checked-off list in the PR where each criterion maps to a concrete deliverable in the diff. | +| **How to satisfy** | Fill in the [Acceptance Criteria Audit Template](./acceptance-criteria-audit-template.md) in the PR template's Section 6 -- one row per criterion, with evidence and a status. | +| **Acceptable evidence** | A completed audit table in the PR where each criterion maps to a concrete deliverable in the diff, not just a checkmark. | ### Partial completion -If a PR intentionally addresses only some criteria, it must: +If a PR intentionally addresses only some criteria, use the audit +template's **Partial** or **Deferred** statuses. It must also: 1. Use `Relates to #N` instead of `Closes #N`. -2. List all criteria and mark only the completed ones. -3. Note which criteria remain and link to any follow-up issues. +2. State what remains in the row's evidence cell. +3. Link any follow-up issues, or note that one should be created. ---