docs(aiwg): add maintainer output templates

This commit is contained in:
Joseph Magly committed 2026-07-15 17:01:29 -04:00
1 parent 400e9e6d24
commit 751707bac1
10 files changed
+249 -1

No files matched your search

+14 -1
View File
@@ -26,7 +26,8 @@ Use it when:
├── README.md ├── README.md
├── agents/ ├── agents/
├── capabilities/ ├── capabilities/
└── skills/ ├── skills/
└── templates/
``` ```
## Skills ## Skills
@@ -51,6 +52,18 @@ Use it when:
- `t3mp3st-merge-train-flow` - `t3mp3st-merge-train-flow`
- `t3mp3st-issue-steward-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 ## Usage
Discover and inspect: Discover and inspect:
@@ -64,6 +64,10 @@ Use this to handle issue threads before implementation.
## Output ## 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 ```markdown
Issue #N — <class> Issue #N — <class>
Evidence: Evidence:
@@ -64,6 +64,9 @@ Never merge:
## Output ## 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 ```markdown
## Merge Train ## Merge Train
@@ -72,6 +72,8 @@ currently runs `vitest run src`.
## Output ## Output
Use `templates/pr-audit-review.md` as the standard review format.
Lead with findings. If none: Lead with findings. If none:
```markdown ```markdown
@@ -67,6 +67,8 @@ Use this skill before any maintainer merge session. It is read-only by default.
## Output ## Output
Use `templates/queue-audit-report.md` as the standard report format.
```markdown ```markdown
## T3MP3ST Queue Audit ## 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>`