Skip to content

docs: add acceptance criteria audit template for PRs - #538

Merged
El-swaggerito merged 1 commit into
Axionvera:mainfrom
jrcity:docs/audit-template
Jul 29, 2026
Merged

docs: add acceptance criteria audit template for PRs#538
El-swaggerito merged 1 commit into
Axionvera:mainfrom
jrcity:docs/audit-template

Conversation

@jrcity

@jrcity jrcity commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Background

Currently, contributors can complete only part of an issue while claiming completion. Reviewers have no standardized way to verify implementation completeness, testing, and documentation updates across pull requests. This lack of structure leads to inconsistent reviews, ambiguous states for incomplete work, and unnecessary back-and-forth between maintainers and contributors.

Implementing a formalized audit template forces contributors to explicitly break down their evidence for every criterion, vastly improving review quality and clarity.

Summary

This pull request introduces a comprehensive 5-column Acceptance Criteria Audit Template to the PR process. It replaces the simple 3-column table previously used and adds clear guidelines on how to report evidence and handle partially completed work.

What Changed

  • Added a 5-column acceptance criteria audit template.
  • Added an Implementation Evidence section to the template.
  • Added a Test Evidence section to the template.
  • Added a Documentation Impact section to the template.
  • Documented "Handling Incomplete Criteria" rules in the self-assessment guide.
  • Updated the contributor documentation (docs/contributor-self-assessment.md) with usage guidance.
  • Updated the PR template (.github/pull_request_template.md) to include the new table format.

Why This Matters

  • For Contributors: Provides absolute clarity on what evidence is expected before requesting a review, removing the guesswork.
  • For Maintainers & Reviewers: Allows for an immediate, at-a-glance assessment of whether an issue is fully complete and how it was verified.
  • For Future Contributors: Establishes a professional standard of accountability, making it easier to see what was intentionally left out of past PRs.

Testing

  • Verified the markdown rendering of the new tables in both the PR template and the contributor self-assessment documentation.
  • Confirmed that the updated instructions read naturally and do not conflict with the existing evaluation readiness checklists.

Documentation

  • .github/pull_request_template.md
  • docs/contributor-self-assessment.md

Acceptance Criteria Checklist

  • Acceptance criteria audit template added
  • Implementation evidence section included
  • Test evidence section included
  • Documentation impact section included
  • Incomplete criteria handling documented
  • PR template or contributor documentation updated

Future Improvements

  • We could potentially add a GitHub Action that parses the PR description and automatically blocks merging if the Status column for any criterion is left blank or uses an invalid value.
  • The evaluation-readiness-checklist.md could be updated in the future to mandate a final pass of this specific 5-column audit.

Related Issue

Closes #496

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.
@El-swaggerito
El-swaggerito merged commit 20c2fd2 into Axionvera:main Jul 29, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add PocketPay Mobile acceptance criteria audit template

2 participants