Review Gate
Use this skill as the last-mile safety checkpoint for agent-generated changes.
It complements PR review tools; it does not replace code review, CI, or human
approval.
Use assets/review-pack-template.md when the user needs a reusable review pack
shape.
When To Run
Run before any of these actions when an agent-generated diff is involved:
- commit
- push
- open or update a PR
- merge or land
- apply a generated patch to user files when the user has not already approved
that exact implementation path
Read-only review, planning, issue triage, and local exploration do not require
this gate unless the next step would land or publish changes.
Operating Contract
- Direct actions: inspect diffs, collect verification evidence, and draft the
review pack.
- Escalate before: commit, push, PR creation, merge, branch deletion, or
applying a generated patch when the user has not approved that exact action.
- Evidence-backed pushback: block landing when verification is stale, sensitive
surfaces lack review, or approval is ambiguous.
- Feedback loop: convert repeated review findings into new checklist items,
verification commands, or Review Pack risk prompts.
Gate States
| State |
Meaning |
Allowed next action |
draft_pack |
Review pack is being assembled. |
Inspect diff and verification only. |
needs_fixes |
Blocking risks or missing evidence exist. |
Patch and rerun the gate. |
awaiting_human |
Pack is complete but no human approval exists. |
Stop before commit, push, PR, merge, or apply. |
approved |
Human explicitly approved the pack in the current thread. |
Proceed with the named action only. |
approved_with_fixes |
Human approved after specific fixes. |
Apply fixes, verify, and record evidence before landing. |
Agents must not self-approve. Prior CI success, a reviewer lane, or a green
local test is evidence for the pack, not approval.
Gotchas
- Approval is action-specific. "Commit it" does not mean "merge it."
- A reviewer lane is independent evidence, not human approval.
- If a fix changes the diff after approval, refresh verification and update the
pack before landing.
Review Pack
Produce this compact pack:
review_gate:
- intent:
- diff_summary:
- files_changed:
- driving_skill_or_issue:
- risks:
- missing_tests_or_verification:
- commands_run:
- evidence:
- open_questions:
- approval_needed_for:
- decision:
Keep findings ranked by severity. Include exact file paths, PR numbers, issue
numbers, command names, and current head SHA when available.
Decision Rules
- If verification is stale, missing, or tied to a different head SHA, set
needs_fixes.
- If the diff touches auth, payments, secrets, permissions,
innerHTML, eval,
shell execution, generated registry, hooks, or high-context files, call that
out explicitly.
- If user approval is ambiguous, set
awaiting_human and ask for the named
action only.
- If the user approves, do exactly the approved action. A commit approval is not
automatically a merge approval.
- If a required fix changes the diff, rerun the relevant verification and update
the pack before landing.
Integration Points
flowguard should call this gate at landing checkpoints. Queue skills may use a
reviewer lane for independent findings, but the Review Gate still records the
human-facing pack and approval state.
For GitHub PRs, combine this gate with current remote truth:
- PR head SHA
- check rollup
- merge state
- GraphQL reviewThreads
- linked issue intent
Verification
For Spellbook changes, the pack usually cites:
git diff --check
python3 ./scripts/validate_skills.py --check
python3 ./scripts/audit_skill_quality.py skill-name
Use project-specific tests for code changes. If a command cannot run, report the
precondition and keep the decision out of approved.
1---2name: review-gate-23description: Use before an agent-produced diff is committed, pushed, opened as a PR, merged, landed, or applied to user files when explicit implementation approval is missing. Trigger for review gate, review pack, approve before landing, diff first then land, human approval, merge gate, commit gate, push gate, or PR readiness. Produces a concise review pack, records risks and verification, and blocks landing until a human explicitly approves or approves with required fixes.4---5
6# Review Gate
7
8Use this skill as the last-mile safety checkpoint for agent-generated changes.
9It complements PR review tools; it does not replace code review, CI, or human
10approval.
11
12Use `assets/review-pack-template.md` when the user needs a reusable review pack
13shape.
14
15## When To Run
16
17Run before any of these actions when an agent-generated diff is involved:
18
19- commit
20- push
21- open or update a PR
22- merge or land
23- apply a generated patch to user files when the user has not already approved
24 that exact implementation path
25
26Read-only review, planning, issue triage, and local exploration do not require
27this gate unless the next step would land or publish changes.
28
29## Operating Contract
30
31- Direct actions: inspect diffs, collect verification evidence, and draft the
32 review pack.
33- Escalate before: commit, push, PR creation, merge, branch deletion, or
34 applying a generated patch when the user has not approved that exact action.
35- Evidence-backed pushback: block landing when verification is stale, sensitive
36 surfaces lack review, or approval is ambiguous.
37- Feedback loop: convert repeated review findings into new checklist items,
38 verification commands, or Review Pack risk prompts.
39
40## Gate States
41
42| State | Meaning | Allowed next action |
43| --- | --- | --- |
44| `draft_pack` | Review pack is being assembled. | Inspect diff and verification only. |
45| `needs_fixes` | Blocking risks or missing evidence exist. | Patch and rerun the gate. |
46| `awaiting_human` | Pack is complete but no human approval exists. | Stop before commit, push, PR, merge, or apply. |
47| `approved` | Human explicitly approved the pack in the current thread. | Proceed with the named action only. |
48| `approved_with_fixes` | Human approved after specific fixes. | Apply fixes, verify, and record evidence before landing. |
49
50Agents must not self-approve. Prior CI success, a reviewer lane, or a green
51local test is evidence for the pack, not approval.
52
53## Gotchas
54
55- Approval is action-specific. "Commit it" does not mean "merge it."
56- A reviewer lane is independent evidence, not human approval.
57- If a fix changes the diff after approval, refresh verification and update the
58 pack before landing.
59
60## Review Pack
61
62Produce this compact pack:
63
64```text
65review_gate:
66- intent:
67- diff_summary:
68- files_changed:
69- driving_skill_or_issue:
70- risks:
71- missing_tests_or_verification:
72- commands_run:
73- evidence:
74- open_questions:
75- approval_needed_for:
76- decision:
77```
78
79Keep findings ranked by severity. Include exact file paths, PR numbers, issue
80numbers, command names, and current head SHA when available.
81
82## Decision Rules
83
84- If verification is stale, missing, or tied to a different head SHA, set
85 `needs_fixes`.
86- If the diff touches auth, payments, secrets, permissions, `innerHTML`, `eval`,
87 shell execution, generated registry, hooks, or high-context files, call that
88 out explicitly.
89- If user approval is ambiguous, set `awaiting_human` and ask for the named
90 action only.
91- If the user approves, do exactly the approved action. A commit approval is not
92 automatically a merge approval.
93- If a required fix changes the diff, rerun the relevant verification and update
94 the pack before landing.
95
96## Integration Points
97
98`flowguard` should call this gate at landing checkpoints. Queue skills may use a
99reviewer lane for independent findings, but the Review Gate still records the
100human-facing pack and approval state.
101
102For GitHub PRs, combine this gate with current remote truth:
103
104- PR head SHA
105- check rollup
106- merge state
107- GraphQL reviewThreads
108- linked issue intent
109
110## Verification
111
112For Spellbook changes, the pack usually cites:
113
114```bash
115git diff --check
116python3 ./scripts/validate_skills.py --check
117python3 ./scripts/audit_skill_quality.py skill-name
118```
119
120Use project-specific tests for code changes. If a command cannot run, report the
121precondition and keep the decision out of `approved`.
majiayu000