Convention: Review Note Lifecycle
Convention: Review Note Lifecycle
Rules for naming, typing, tagging, and cleaning up review notes created by
skill-review-ticket.Rule
Review notes use slug
review-{board_item_id}-{YYYY-MM-DD}, note_type review, and tags review,{verdict} where verdict is ready, needs-refinement, or block. Review notes for board items in done can be deleted after 7 days; superseded intermediate reviews can be deleted once a final ready verdict exists.Rationale
Three sources previously gave conflicting guidance:
skill-review-ticket (board item ID, note_type review), template-review (issue number, note_type doc), and note-conventions (review-{repo}-{pr-number}). This caused 3 review notes to be created with wrong note_type (doc instead of review) during the 2026-03-28 session. Without a single authoritative convention, review notes accumulate without cleanup rules and note_type queries return incomplete results. The slug uses board item ID because board items are the canonical identifier in the kanban workflow -- Forgejo issue numbers can differ across repos and are secondary.Examples
| Correct | Incorrect | Why |
|---|---|---|
| <code>review-464-2026-03-27</code> | <code>review-206-2026-03-27</code> | 464 is the board item ID; 206 is the Forgejo issue number. Use board item ID. |
| <code>review-364-2026-03-27-v2</code> | <code>review-364-2026-03-27-second</code> | Re-reviews use <code>-v2</code> or <code>-r2</code> suffix, not free-form text. |
| note_type: <code>review</code> | note_type: <code>doc</code> | <code>review</code> is a valid NoteType. Do not use <code>doc</code> as a workaround. |
| tags: <code>review,ready</code> | tags: <code>review</code> | Verdict tag is required alongside the <code>review</code> tag. |
| status: <code>null</code> | status: <code>active</code> | Review notes do not use status. Verdict is in the heading and tags. |
Enforcement
SOP-enforced:
skill-review-ticket step 12 creates review notes with the correct naming, type, and tags. The sop-board-workflow gates todo-to-next_up on a review note existing. Cleanup is convention only (no automated deletion mechanism yet).Related
skill-review-ticket— the skill that creates review notes (authoritative source for naming)template-review— template for review note content structure (naming convention section needs update to match this convention)skill-refine-ticket— consumes review notes to apply refinement fixessop-board-workflow— defines the todo-to-next_up review gatenote-conventions— lists review as an active note type with slug pattern