[Audit] Review governance & change management documentation #20

title: "[Audit] Review governance & change management documentation"
type: "Audit"
labels:

• governance
• audit
• maintenance
  template: ".github/ISSUE_TEMPLATE/21-audit.md"
  template_ref: "@lightspeedwp/.github/files/.github/ISSUE_TEMPLATE/21-audit.md"

Audit Summary

Conduct a process and documentation audit of governance and change management content in the lightspeedwp/.github repository.

The audit should confirm that governance-related documentation is current, internally consistent, easy to follow, and aligned with the repository’s present operating model. This includes reviewing maintainer and contact information, ownership and approval expectations, documented update processes, and whether governance or process changes should have a lightweight changelog or revision history.

The outcome should be a clear record of findings, risks, and recommended remediation work, with follow-up issues created where changes are larger than a small documentation correction.

Audit Checklist / Scope

• Confirm the audit scope and target files before starting
• Review AGENTS.md for governance language, ownership clarity, and change-management references
• Review .github/custom-instructions.md for repository boundary rules, governance expectations, and possible drift from current practice
• Review relevant files in .github/instructions/ for overlapping, conflicting, stale, or unclear governance/process guidance
• Review any community-health or repository-governance documents that define maintainer responsibilities, contribution flow, review expectations, or documentation ownership
• Verify maintainer names, team references, ownership notes, and contact points are accurate and consistent
• Check whether governance/process updates are currently tracked anywhere in the repository
• Assess whether a changelog, revision log, or other lightweight governance history should be added
• Identify broken, stale, or misleading internal references and cross-links
• Identify duplicated guidance that should be consolidated or clarified
• Document all findings and classify them by severity or urgency
• Map each meaningful finding to a remediation action or follow-up issue
• Separate quick wins from larger structural follow-up work
• Scope defined and agreed
• Areas/components listed
• Audit tools or standards referenced
• Risks and findings documented
• Remediation actions mapped

Findings / Risks

Use this section to record findings during the audit.

Expected areas of risk include:

• outdated maintainer or contact information
• conflicting governance guidance across top-level and repo-local instructions
• unclear ownership for approving or maintaining governance documentation
• missing or undocumented change-management steps
• lack of visible history for governance/process updates
• stale links, references, or migration notes
• duplicated content that increases maintenance cost and drift risk

Potential impact includes contributor confusion, inconsistent reviews, governance decisions being applied unevenly, and documentation becoming harder to trust over time.

Remediation Actions

• Correct outdated maintainer, owner, or contact details
• Clarify governance ownership and review expectations where ambiguous
• Consolidate duplicated or conflicting governance guidance
• Update stale links, references, and migration notes
• Document the expected process for making governance or process changes
• Decide whether governance/process changes require a dedicated changelog, revision log, or dated update section
• Create follow-up issues for larger documentation or structural changes that should not be completed as part of this audit
• Record rationale for any proposed governance change-tracking approach to keep maintenance overhead proportionate

Acceptance Criteria

• Audit scope and checklist completed
• Findings and risks documented
• Remediation actions assigned and tracked
• Documentation/changelog updated (if applicable)
• PR uses correct branch prefix (audit/)
• In-scope governance and change-management files reviewed
• Maintainer/contact information verified or discrepancies recorded
• Recommendation made on whether to introduce governance/process change tracking
• Follow-up issues created for material remediation work outside the audit itself

Additional Context

Issue: #20
Issue type: Audit

Template used:

• .github/ISSUE_TEMPLATE/21-audit.md
• @lightspeedwp/.github/files/.github/ISSUE_TEMPLATE/21-audit.md

Initial issue notes:

• Periodically review and update maintainer/contact info
• Consider adding a changelog for governance/process changes

Suggested review targets:

• AGENTS.md
• .github/custom-instructions.md
• relevant governance/process files under .github/instructions/
• related repository documentation that defines ownership, process, or change control

Audit standards and constraints:

• Use UK English
• Keep recommendations practical, minimal, and maintainable
• Prefer lightweight governance controls unless a larger solution has clear ROI
• Keep this issue focused on audit, findings, and follow-up planning rather than broad restructuring

Definition of Ready (DoR)

• Audit scope, checklist, and goals defined
• Areas/components listed
• Dependencies and standards mapped
• Relevant governance files identified
• Audit output format agreed: findings, risks, and follow-up actions

Definition of Done (DoD)

• Audit performed and findings documented
• Remediation actions assigned
• Documentation/changelog updated (if applicable)
• PR uses correct branch prefix (audit/)
• Any larger remediation work split into follow-up issues
• Final recommendation recorded for governance/process change tracking