pal-e-docs

Review Template

template-review Template

active template
Project

Review Template

Every ticket that reaches next_up must have a review note before moving to in_progress. The review note is the left-side quality gate — it proves the ticket is scoped correctly, traceable, and ready for an agent to execute.
Principle: reviewed beats assumed. A ticket isn't ready until a fresh-context agent has verified its scope, targets, and dependencies.

When to Create

  • Before execution, after scoping. The ticket is in todo or next_up. Betty Sue (or the /review-ticket skill) spawns a QA agent to review before dispatching work.
  • Who creates it: A fresh-context QA agent via skill-review-ticket. The agent reads the Forgejo issue, board item labels, file system, and pal-e-docs conventions — then writes the review note.
  • The signal: If the review cannot produce a READY verdict, the ticket needs refinement before any agent touches code.

Verdicts

The h2 heading of every review note declares the verdict:
Verdict Meaning Board Action Tag
<strong>READY</strong> Ticket is fully scoped, traceable, and executable. Agent can proceed. Move to <code>in_progress</code>, dispatch agent. <code>ready</code>
<strong>NEEDS_REFINEMENT</strong> Ticket has gaps — missing targets, unclear AC, dependency questions. Fixable without rethinking the ticket. Stay in <code>todo</code>/<code>next_up</code>. Address recommendations, re-review. <code>needs-refinement</code>
<strong>BLOCK</strong> Fundamental problem — wrong repo, missing prerequisite, scope too large to execute as one ticket. Move back to <code>backlog</code> or split into sub-tickets. <code>block</code>

Template

Naming Convention

Slug: review-{issueNumber}-{YYYY-MM-DD} (e.g., review-464-2026-03-27)
Note type: doc (until review is added to NoteType enum)
Tags: review + one verdict tag (ready, needs-refinement, or block)
Status: null — review notes do not use status. The verdict is in the heading and tags.
Project: same as the ticket being reviewed

Review Dimensions

Section What It Checks Common Failures
Template Completeness All required issue fields are present and filled Missing file targets, vague user story, no test expectations
Traceability Board item has story: and arch: labels, Forgejo issue exists Unlabeled board items, orphaned issues
File Targets Paths exist (or parent dirs do), targets are specific "Update the config" with no path specified
Repo Placement Work belongs in the specified repo Cross-repo work filed as single-repo ticket
Dependencies All prerequisites are satisfied or explicitly tracked Assuming a PR is merged when it is still open
Acceptance Criteria Each AC is testable and specific "It works" instead of "curl returns 200 with JSON body"
Blast Radius Scope of impact is understood and manageable 9-repo rollout with no ordering strategy
Decomposition Ticket fits the three-thing limit and five-minute rule Epic-sized ticket that should be a tracking issue

Relationship to Board Flow

The review gate is the left-side mirror of the validation gate on the right side. Left gate: "is the scope right?" Right gate: "does it actually work?" Together they enforce quality on both ends of the execution pipeline.

DORA Integration

  • Change Failure Rate (CFR): The ready/needs-refinement/block ratio is a leading CFR signal. High NEEDS_REFINEMENT rates mean tickets are being created with insufficient scope — the process upstream of execution is producing defects.
  • Lead Time: Time spent in review refinement loops adds to lead time, but prevents much larger delays from poorly-scoped agent work.
  • Deployment Frequency: Well-reviewed tickets execute faster and merge sooner, increasing throughput.
  • template-validation — sibling template for the right-side gate (post-merge verification)
  • note-conventions — canonical reference for note types, slugs, tags, and linking
  • skill-review-ticket — the agent skill that creates review notes using this template
  • skill-review-pr — the code-side review skill (post-implementation mirror)
  • sop-board-workflow — column semantics and the review gate definition
  • template-issue — the issue template whose fields Template Completeness checks against
  • template-board — sub-board template (review notes may trigger decomposition into sub-boards)