# Template: canonical state comments

Use these only for workflow-changing comments. Casual discussion does not need
the full template.

## Issue

```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

```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

```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>
```