AP-04 — Documentation Governance Workflow¶
Strategy Reference¶
- Objective 3 — Documentation as Living Knowledge (by month 9)
- Section 12, Phase 1 — Documentation governance workflow live (AI-audited PRs)
Goal¶
By month 9, all internal documentation is governed by an AI-audited workflow. No documentation change is merged without:
- Automated compliance verification (frontmatter, links, naming, conventions)
- Named owner approval
Scope¶
In scope:
- All Markdown content under the Documentation/ repository
- All file types governed by PROJECT_INSTRUCTIONS.md conventions
- Pull requests in feodasalesadmin/documentation (and any equivalents)
Out of scope:
- Code repositories outside Documentation/
- Generated artefacts (build outputs, _site/)
Deliverables¶
- Convention codification —
PROJECT_INSTRUCTIONS.mdrules represented as machine-checkable rules where possible - AI-audit job — runs on every PR, produces a report on compliance gaps
- Required-reviewer assignment — folder owner must approve PRs touching their folder
- CI gating — PRs blocked from merge until checks pass and owner approval is recorded
- Owner registry — explicit map of folder paths → named owner
Milestones¶
| Milestone | Target Month | Exit Criteria |
|---|---|---|
| Convention rules formalised | Month 2 | Machine-checkable rule set documented |
| AI-audit job prototype | Month 4 | Job runs on demo PR; produces useful output |
| Owner registry published | Month 5 | Every folder has a named owner |
| PR gating enabled | Month 7 | CI blocks merge on failed checks or missing owner approval |
| 100% PR coverage verified | Month 9 | One quarter of PRs all governed |
Dependencies¶
- AP-03 — Approved Provider List: the AI used by the audit job must itself be on the approved list
- AP-05 — Audit Logging Infrastructure: audit job invocations and outputs must be logged
Risks & Mitigations¶
| Risk | Mitigation |
|---|---|
| AI audit produces false positives that slow PRs | Tune progressively; allow override with justification |
| Owners are unresponsive and bottleneck PRs | Owner SLAs; named delegates; escalation path |
Convention rules drift from PROJECT_INSTRUCTIONS.md |
Single source of truth for conventions; rule set is generated from it where feasible |
Success Measures¶
- Documentation compliance score ≥98% by month 9 (frontmatter completeness, link validity, changelog completeness)
- 100% of PRs receive AI-audit run
- Median PR-to-merge time does not regress materially
- Owner approval recorded on 100% of merged PRs
Status Log¶
| Date | Status | Notes |
|---|---|---|
| 2026-04-22 | Not Started | Action plan created. Awaiting Phase 1 kickoff. |