Gitea-Tools/docs/canonical-state-comments.md

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.

## 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.

## 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.

## 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.