docs(aiwg): add maintainer output templates

2026-07-15 17:01:29 -04:00
1 parent 400e9e6d24
commit 751707bac1
@@ -26,7 +26,8 @@ Use it when:
 ├── README.md
 ├── agents/
 ├── capabilities/
-└── skills/
+├── skills/
+└── templates/
 ```

 ## Skills
@@ -51,6 +52,18 @@ Use it when:
 - `t3mp3st-merge-train-flow`
 - `t3mp3st-issue-steward-flow`

+## Templates
+
+- `queue-audit-report.md` — full PR/issue queue state and suggested merge order.
+- `pr-audit-review.md` — findings-first PR audit with SHA, checks, decision, and
+  residual risk.
+- `issue-response.md` — issue classification, evidence, action, and maintainer
+  response draft.
+- `merge-train-report.md` — per-PR merge results, stop reason, issue
+  reconciliation, and next candidate.
+- `maintainer-action-items.md` — owner/action/blocker/follow-up list for user
+  communication and handoff.
+
 ## Usage

 Discover and inspect:
@@ -64,6 +64,10 @@ Use this to handle issue threads before implementation.

 ## Output

+Use `templates/issue-response.md` as the standard issue report and draft-comment
+format. Use `templates/maintainer-action-items.md` when the issue produces
+follow-up work.
+
 ```markdown
 Issue #N — <class>
 Evidence:
@@ -64,6 +64,9 @@ Never merge:

 ## Output

+Use `templates/merge-train-report.md` as the standard merge-session report and
+`templates/maintainer-action-items.md` when follow-up work remains.
+
 ```markdown
 ## Merge Train

@@ -72,6 +72,8 @@ currently runs `vitest run src`.

 ## Output

+Use `templates/pr-audit-review.md` as the standard review format.
+
 Lead with findings. If none:

 ```markdown
@@ -67,6 +67,8 @@ Use this skill before any maintainer merge session. It is read-only by default.

 ## Output

+Use `templates/queue-audit-report.md` as the standard report format.
+
 ```markdown
 ## T3MP3ST Queue Audit

@@ -0,0 +1,39 @@
+---
+name: issue-response
+description: Issue stewardship template for classification, evidence, recommended maintainer action, and user-facing response draft.
+---
+
+# Issue Stewardship
+
+Issue: `#<number>`
+Title: `<title>`
+Reporter: `<user>`
+Date: `<YYYY-MM-DD>`
+
+## Classification
+
+Class: `<support-answer | bug-address | feature-track | security-contact | linked-pr | resolved | needs-info>`
+
+## Evidence
+
+- `<issue body/comment/code/PR evidence>`
+
+## Recommended Action
+
+Action: `<comment | close | link PR | address-issues | feature-track | defer>`
+
+Rationale:
+
+- `<why this action is correct>`
+
+## Draft Maintainer Response
+
+```markdown
+<concise user-facing response>
+```
+
+## Follow-Up
+
+| Owner | Action | Due / Recheck | Status |
+| --- | --- | --- | --- |
+| `<owner>` | `<action>` | `<date/event>` | `<open/done/blocked>` |
@@ -0,0 +1,33 @@
+---
+name: maintainer-action-items
+description: Maintainer action-item tracker for user-facing handoff after queue audits, issue reviews, PR audits, and merge sessions.
+---
+
+# Maintainer Action Items
+
+Date: `<YYYY-MM-DD>`
+Source: `<queue audit | PR audit | issue stewardship | merge train>`
+
+## Open Actions
+
+| Priority | Owner | Item | Source | Blocker | Recheck |
+| --- | --- | --- | --- | --- | --- |
+| `<P0/P1/P2>` | `<owner>` | `<action>` | `<PR/issue/link>` | `<blocker or none>` | `<date/event>` |
+
+## User-Facing Updates Needed
+
+| Audience | Channel | Message Purpose | Draft / Link |
+| --- | --- | --- | --- |
+| `<reporter/contributor/maintainer>` | `<issue/PR/discussion>` | `<purpose>` | `<draft or reference>` |
+
+## Completed This Session
+
+| Item | Evidence |
+| --- | --- |
+| `<completed item>` | `<link/check/commit>` |
+
+## Deferred
+
+| Item | Reason | Revisit Trigger |
+| --- | --- | --- |
+| `<item>` | `<reason>` | `<trigger>` |
@@ -0,0 +1,46 @@
+---
+name: merge-train-report
+description: Maintainer merge-session report with per-PR gates, merge results, issue reconciliation, stop reasons, and next candidate.
+---
+
+# Merge Train Report
+
+Date: `<YYYY-MM-DD>`
+Repository: `elder-plinius/T3MP3ST`
+Operator: `<maintainer>`
+Method default: `<squash | merge | rebase>`
+
+## Preflight
+
+- Queue audit source: `<date/link/summary>`
+- Local branch: `<branch>`
+- Main baseline: `<sha>`
+- GitHub auth: `<confirmed/not confirmed>`
+
+## Merged
+
+| PR | Title | Head SHA | Method | Checks | Linked Issues | Outcome |
+| --- | --- | --- | --- | --- | --- | --- |
+| `#` | `<title>` | `<sha>` | `<method>` | `<pass/evidence>` | `<issues>` | `<merged/closed/commented>` |
+
+## Stopped Before
+
+| PR | Reason | Required Follow-Up |
+| --- | --- | --- |
+| `#` | `<reason>` | `<follow-up>` |
+
+## Issue Reconciliation
+
+| Issue | Expected Outcome | Actual Outcome | Action Taken |
+| --- | --- | --- | --- |
+| `#` | `<auto-close/comment/remain open>` | `<actual>` | `<action>` |
+
+## Next Recommended Candidate
+
+- PR: `#<number>`
+- Reason: `<why next>`
+- Required check before merge: `<check>`
+
+## Session Notes
+
+- `<note>`
@@ -0,0 +1,54 @@
+---
+name: pr-audit-review
+description: Findings-first maintainer PR audit template with exact SHA, verification evidence, decision, and residual risk.
+---
+
+# PR Audit
+
+PR: `#<number>`
+Title: `<title>`
+Head SHA: `<sha>`
+Base: `main`
+Reviewer: `<name/tool>`
+Date: `<YYYY-MM-DD>`
+
+## Findings
+
+| Severity | File / Area | Finding | Required Change |
+| --- | --- | --- | --- |
+| `<blocking/non-blocking>` | `<path:line or area>` | `<finding>` | `<change>` |
+
+If there are no blocking findings:
+
+> No blocking findings.
+
+## Verification
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| `<CI check or local command>` | `<pass/fail/not run>` | `<URL/output summary>` |
+
+## Review Decision
+
+Decision: `<approve | request changes | comment | hold>`
+
+Reason:
+
+- `<short reason>`
+
+## Residual Risk
+
+- `<risk, assumption, or none>`
+
+## Suggested Maintainer Comment
+
+```markdown
+Reviewed PR #<number> at `<sha>`.
+
+<findings or no-blocking-findings statement>
+
+Verification:
+- <checks>
+
+Decision: <decision>
+```
@@ -0,0 +1,52 @@
+---
+name: queue-audit-report
+description: Full T3MP3ST maintainer queue audit report for open PRs, issues, readiness, blockers, and suggested merge order.
+---
+
+# T3MP3ST Queue Audit
+
+Date: `<YYYY-MM-DD>`
+Repository: `elder-plinius/T3MP3ST`
+Audit scope: `<all open PRs/issues | filtered scope>`
+
+## Summary
+
+- Ready merge candidates: `<count>`
+- Needs re-audit: `<count>`
+- Blocked or rebase needed: `<count>`
+- Issues needing maintainer action: `<count>`
+- Recommended next action: `<one sentence>`
+
+## Ready Merge Candidates
+
+| Order | PR | Title | Head SHA | Evidence | Risk | Linked Issues |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | `#` | `<title>` | `<sha>` | `<CI/review/local checks>` | `<low/medium/high>` | `<issues>` |
+
+## Needs Re-Audit
+
+| PR | Reason | Required Checks | Owner |
+| --- | --- | --- | --- |
+| `#` | `<stale SHA/no CI/new comments/high-risk area>` | `<checks>` | `<maintainer>` |
+
+## Blocked / Rebase Needed
+
+| PR | Blocker | Maintainer Action | Unblock Condition |
+| --- | --- | --- | --- |
+| `#` | `<conflict/failing CI/changes requested/question>` | `<action>` | `<condition>` |
+
+## Issue Actions
+
+| Issue | Class | Evidence | Next Action |
+| --- | --- | --- | --- |
+| `#` | `<close-via-pr/needs-response/address-issues/feature-track/defer>` | `<evidence>` | `<action>` |
+
+## Merge Train Recommendation
+
+1. `<PR # and reason>`
+2. `<PR # and reason>`
+3. `<PR # and reason>`
+
+## Notes And Risks
+
+- `<risk or assumption>`