---
name: gate-review
description: Generate a checkbox review file for a gate output and verify it when APPROVED is received. Called at every gate pause point in both dev and tester workflows.
keywords: gate review, checkbox, review file, approved, mandatory review
---

# Gate Review — Mandatory Checkbox Protocol

> **Purpose:** Prevent blind approval. Every gate output gets a review file with one checkbox per key section. Developer checks off items in VSCode. APPROVED is only accepted after all items are checked.

---

## When to invoke this skill

This skill is invoked in **two modes** at every gate pause point:

| Mode | When | What AI does |
|------|------|-------------|
| `generate` | Immediately after AI finishes gate output | Write `.aiflow/review/gate-N-[ticket].md` |
| `verify` | When developer types `APPROVED` | Run `ak review check`, interpret result, proceed or block |

---

## File Naming Rules

**Standard gates (Dev and Tester):**

```
.aiflow/review/gate-[N]-[ticket-id].md
```

**Tester Gate 2 sub-phases only:**

Tester Gate 2 produces multiple review files — one per sub-phase. Use a letter suffix instead of the base gate number alone:

```
.aiflow/review/gate-2a-[ticket-id].md   ← first sub-phase
.aiflow/review/gate-2b-[ticket-id].md   ← second sub-phase
.aiflow/review/gate-2c-[ticket-id].md   ← third sub-phase
(and so on)
```

> **IMPORTANT:** Do NOT use `gate-2-[ticket].md` for Tester Gate 2 sub-phases. Always use the lettered form (`gate-2a`, `gate-2b`, etc.) so each sub-phase has its own distinct review file and the `ak review check` command can target the correct file.

---

## Mode 1: GENERATE — Prepare Inline Review & Output Document

When generating the output for a gate (e.g. `requirement.md` or `plan.md`), follow these steps:

### Step 1: Ensure review directories and comments database exist

1. Always create the directory `.aiflow/review/` if it doesn't exist.
2. Check if `.aiflow/review/comments-[ticket-id].json` exists (where `[ticket-id]` comes from `.aiflow/context/current.json` → `ticketId` field).
3. If the JSON file does not exist, initialize it by writing an empty array `[]` (or `{ "comments": [] }`) to it. This ensures that the CLI verification commands do not fail due to a missing file when there are no comments.

### Step 2: Write the gate output file
Write the gate output file (e.g. `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`, `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`, or `docs/ak-[project]/...`) as specified by the gate instructions.

Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).

### Step 3: Display gate pause message

Instruct the user to review the generated document. Tell them that they can hover over any line and add inline comments in VS Code using the native commenting UI, or edit the file to add standard HTML comments `<!-- comment -->` if they are not using the VS Code extension.

Display in chat:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️  GATE [N] PAUSED — REVIEW REQUIRED

📋 Open in VS Code: [path/to/generated/file.md](path/to/generated/file.md)

  • Review the generated document content directly.
  • Hover over any line to add specific comments (inline review).
  • Mark comments as "Resolved" in VS Code once addressed.
  • Type APPROVED when done.

⚠️  APPROVED will not be accepted until all inline comments are resolved.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Mode 2: VERIFY — Check Comments and Checklist on APPROVED

When the developer types `APPROVED`, run this check:

### Step 1: Run CLI check

```bash
ak review check --gate [N] --ticket [ticket-id]
```

### Step 2: Interpret result

**Exit code 0 — all checked & resolved:**
- Gate proceeds normally
- Run telemetry: `ak gate [N] approved --ticket [ticket-id]`
- Continue to next gate

**Exit code 1 — file missing:**
- AI response: "The review session files weren't found. Let me prepare them."
- Re-run Mode 1 (initialize `comments-[ticket-id].json` and output file) and display pause message.

**Exit code 1 — items with comments (need revision):**
If the CLI reports unresolved comments, the AI must:
1. Read the unresolved comments returned by the CLI (which include file path, line number, and comment text).
2. Read the source file at those line numbers to understand the context.
3. Update the specific sections of the document to address the comments.
4. Tell the user what was updated, ask them to mark the comment thread as resolved in VS Code, and type `APPROVED`.

---

## Mandatory Rules

- ❌ **NEVER** accept `APPROVED` without first running `ak review check`
- ✅ **ALWAYS** ensure `.aiflow/review/` directory exists (use `mkdir -p`)
- ✅ **ALWAYS** initialize `.aiflow/review/comments-[ticket-id].json` with `[]` if not present when starting a gate pause.
- ✅ **ALWAYS** use the ticket ID from `.aiflow/context/current.json` in the file name
- ✅ **ALWAYS** use lettered suffixes (`gate-2a`, `gate-2b`, …) for Tester Gate 2 sub-phases — never plain `gate-2`