From 7ce7b01d19544b74ae0369c696a7cfa4d78d9559 Mon Sep 17 00:00:00 2001
From: jrcity <redemptionjonathan1@gmail.com>
Date: Wed, 29 Jul 2026 20:10:26 +0100
Subject: [PATCH] docs: add acceptance criteria audit template for PRs

Replaces the basic 3-column acceptance criteria table with a comprehensive 5-column audit template in both the PR template and the contributor self-assessment guide. Adds explicit instructions for handling and documenting partially completed work.
---
 .github/pull_request_template.md    | 10 +++++-----
 docs/contributor-self-assessment.md | 26 +++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 79aec23..1c739c5 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -46,13 +46,13 @@ requesting review. Include concise evidence below; use
 
 <!-- Write "None known" only after checking for limitations. -->
 
-### Acceptance Criteria
+### Acceptance Criteria Audit
 
-<!-- Map your changes to the issue acceptance criteria. See the [Traceability Table Guide](../docs/traceability-table.md) for how to fill this out. -->
+<!-- Map your changes to the issue acceptance criteria. See the [Traceability Table Guide](../docs/traceability-table.md) and docs/contributor-self-assessment.md for guidance on handling incomplete criteria and filling each field. -->
 
-| Acceptance criterion | Implementation or evidence | Status |
-| --- | --- | --- |
-| <!-- Criterion --> | <!-- File, test, screenshot, or explanation --> | Pass / Not applicable |
+| Acceptance Criterion | Implementation Evidence | Test Evidence | Documentation Impact | Status |
+| --- | --- | --- | --- | --- |
+| <!-- Criterion --> | <!-- File, screenshot, or explanation --> | <!-- Test file or manual check --> | <!-- Docs changed, or N/A --> | Complete / Partial / Not Applicable / Not Implemented |
 
 ## Screenshots or Recordings
 
diff --git a/docs/contributor-self-assessment.md b/docs/contributor-self-assessment.md
index 1237afe..51476d8 100644
--- a/docs/contributor-self-assessment.md
+++ b/docs/contributor-self-assessment.md
@@ -81,20 +81,36 @@ describe its user impact and link a follow-up issue when one exists.
 
 **Known limitations and follow-up work:**
 
-### Acceptance Criteria
+### Acceptance Criteria Audit
 
 - [ ] I checked every acceptance criterion in the linked issue against the
       implementation and evidence.
 - [ ] Every criterion is satisfied, or an exception has been explicitly agreed
       with a maintainer and documented below.
 
-<!-- Map each acceptance criterion to implementation or verification evidence. -->
+#### How to Complete the Audit Template
+
+- **Acceptance Criterion:** Copy the exact requirement from the issue.
+- **Implementation Evidence:** List the files modified, attach a screenshot, or explain the change.
+- **Test Evidence:** Reference the automated test file, or describe the manual verification step.
+- **Documentation Impact:** List any updated documentation files, or write "None needed" if applicable.
+- **Status:** Must be exactly one of: `Complete`, `Partial`, `Not Applicable`, `Not Implemented`.
+
+#### Handling Incomplete Criteria
+
+When a piece of work cannot be fully completed in the current pull request:
+- Explain why a criterion is incomplete in the *Implementation Evidence* column.
+- Link to follow-up issues if applicable.
+- Clearly distinguish completed work from future work.
+- Avoid marking incomplete work as complete (use `Partial` or `Not Implemented`).
+
+<!-- Map each acceptance criterion to implementation or verification evidence using the audit template below. -->
 
 **Acceptance criteria confirmation:**
 
-| Acceptance criterion | Implementation or evidence | Status |
-| --- | --- | --- |
-| <!-- Criterion --> | <!-- File, test, screenshot, or explanation --> | Pass / Not applicable |
+| Acceptance Criterion | Implementation Evidence | Test Evidence | Documentation Impact | Status |
+| --- | --- | --- | --- | --- |
+| <!-- Criterion --> | <!-- File, screenshot, or explanation --> | <!-- Test file or manual check --> | <!-- Docs changed, or N/A --> | Complete / Partial / Not Applicable / Not Implemented |
 
 ### Final Confirmation