sysadminandClaude Opus 4.8
9235f3a23c
Add canonical issue/PR/discussion state comment templates and validators, final-report rules for STATE/WHO_IS_NEXT/NEXT_ACTION/NEXT_PROMPT, and queue-controller guidance. Posting enforcement remains in #496. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
184 lines
3.3 KiB
Markdown
184 lines
3.3 KiB
Markdown
# Canonical State Comments
|
|
|
|
Gitea is the durable system of record for workflow continuation. When a
|
|
comment changes issue, PR, or discussion state, it should leave enough
|
|
information for the next role to continue without private chat history.
|
|
|
|
Canonical comments answer:
|
|
|
|
- what state the object is in
|
|
- who acts next
|
|
- what the next actor should do
|
|
- the exact prompt the next actor should run
|
|
- which proof, blocker, or dependency matters
|
|
|
|
Non-workflow discussion comments do not need this template.
|
|
|
|
## Issue State
|
|
|
|
Use this when an issue becomes ready, blocked, in progress, PR-open,
|
|
superseded, merged, or otherwise changes workflow direction.
|
|
|
|
```text
|
|
## Canonical Issue State
|
|
|
|
STATE:
|
|
<ready-for-author | in-progress | blocked | PR-open | needs-review | ready-to-merge | merged | closed | superseded>
|
|
|
|
WHO_IS_NEXT:
|
|
<controller | author | reviewer | merger | reconciler | user>
|
|
|
|
NEXT_ACTION:
|
|
<specific one-sentence action>
|
|
|
|
NEXT_PROMPT:
|
|
<paste-ready prompt for the next role>
|
|
|
|
WHAT_HAPPENED:
|
|
<latest meaningful event>
|
|
|
|
WHY:
|
|
<decision rationale>
|
|
|
|
RELATED_DISCUSSION:
|
|
<link/reference or none>
|
|
|
|
RELATED_PRS:
|
|
- #...
|
|
|
|
BRANCH:
|
|
<branch or none>
|
|
|
|
HEAD_SHA:
|
|
<40-character SHA or none>
|
|
|
|
VALIDATION:
|
|
<tests/proofs or none>
|
|
|
|
BLOCKERS:
|
|
<blocker and unblock condition, or none>
|
|
|
|
LAST_UPDATED_BY:
|
|
<identity/profile/date>
|
|
```
|
|
|
|
## PR State
|
|
|
|
Use this when a PR needs review, receives changes requested, is approved,
|
|
is stale, is superseded, or becomes ready for merge.
|
|
|
|
```text
|
|
## Canonical PR State
|
|
|
|
STATE:
|
|
<needs-review | changes-requested | approved | stale-approval | ready-to-merge | merged | blocked | superseded>
|
|
|
|
WHO_IS_NEXT:
|
|
<controller | author | reviewer | merger | reconciler | user>
|
|
|
|
NEXT_ACTION:
|
|
<specific one-sentence action>
|
|
|
|
NEXT_PROMPT:
|
|
<paste-ready prompt for the next role>
|
|
|
|
WHAT_HAPPENED:
|
|
<latest meaningful event>
|
|
|
|
WHY:
|
|
<decision rationale>
|
|
|
|
ISSUE:
|
|
#...
|
|
|
|
BASE:
|
|
<branch>
|
|
|
|
HEAD:
|
|
<branch>
|
|
|
|
HEAD_SHA:
|
|
<40-character SHA>
|
|
|
|
REVIEW_STATUS:
|
|
<none | approved | changes-requested | stale | contaminated>
|
|
|
|
VALIDATION:
|
|
<tests/proofs>
|
|
|
|
BLOCKERS:
|
|
<blockers or none>
|
|
|
|
SUPERSEDES:
|
|
<PRs or none>
|
|
|
|
SUPERSEDED_BY:
|
|
<PR or none>
|
|
|
|
MERGE_READY:
|
|
<yes/no and why>
|
|
|
|
LAST_UPDATED_BY:
|
|
<identity/profile/date>
|
|
```
|
|
|
|
## Discussion Summary
|
|
|
|
Discussions should normally have at least five substantive comments before
|
|
conversion into issues. A controller may waive that only for tiny mechanical,
|
|
urgent, or explicitly trivial work.
|
|
|
|
```text
|
|
## Canonical Discussion Summary
|
|
|
|
STATE:
|
|
<needs-more-discussion | ready-for-issues | issues-created | closed>
|
|
|
|
WHO_IS_NEXT:
|
|
<controller | author | reviewer | user>
|
|
|
|
DECISION:
|
|
<what was decided>
|
|
|
|
WHY:
|
|
<reasoning and tradeoffs>
|
|
|
|
SUBSTANTIVE_COMMENTS:
|
|
<count and summary>
|
|
|
|
ISSUES_TO_CREATE_OR_CREATED:
|
|
- #...
|
|
|
|
DEPENDENCY_ORDER:
|
|
<order or none>
|
|
|
|
NON_GOALS:
|
|
<non-goals>
|
|
|
|
OPEN_QUESTIONS:
|
|
<questions or none>
|
|
|
|
NEXT_ACTION:
|
|
<specific one-sentence action>
|
|
|
|
NEXT_PROMPT:
|
|
<paste-ready prompt for the next role>
|
|
|
|
LAST_UPDATED_BY:
|
|
<identity/profile/date>
|
|
```
|
|
|
|
## Validation Rules
|
|
|
|
The final-report validator rejects canonical state update claims when the
|
|
report omits the canonical block or when the block lacks:
|
|
|
|
- `STATE`
|
|
- `WHO_IS_NEXT`
|
|
- `NEXT_ACTION`
|
|
- `NEXT_PROMPT`
|
|
|
|
It also rejects vague next actions such as `continue`, ready-to-merge states
|
|
without approval/head-SHA proof, superseded states without canonical item
|
|
proof, and blocked states without an unblock condition.
|