---
name: gate-review
description: Pause at a gate for human review of the gate output and, when APPROVED is received, verify that no inline review comment is left unresolved. Called at every gate pause point in both dev and tester workflows.
keywords: gate review, inline comments, approved, review pause
---

# Gate Review — Inline Comment Protocol

> **Purpose:** Pause at every gate so the reviewer reads the real gate output, and do not accept APPROVED while an inline review comment is still unresolved. There is **no checklist to tick**: do not create a `.aiflow/review/gate-N-[ticket].md` checkbox file, and do not ask the reviewer to tick items.

---

## 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 | Initialize `.aiflow/review/comments-[ticket].json`, display the pause message |
| `verify` | When developer types `APPROVED` | Run `ak review check`, interpret result, proceed or block |

Tester Gate 2 sub-phases pass the lettered gate (`2a`, `2b`, …) to `ak review check --gate`, so the inline comments of each sub-phase are checked separately.

---

## 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 2b: Terminology self-check before pausing

Every gate of every workflow pauses through this skill, so run this check here before showing the pause message. Check the gate output against `custom/rules/domain-terminology.md` and `AK-Docs/00.Project-Overview/Glossary.md`:

- Same terms as the earlier documents of this ticket/functionId (QnA-Log, Analysis, UC Spec, System Requirement, requirement.md, test case) — no synonyms.
- No self-translated project term, no self-coined subsystem / menu / screen-area name. Grep the output for words often coined instead of project terms (VI: `cửa hàng|khách hàng|người mua|nhà cung cấp|trang quản trị|cổng|nhóm|sản phẩm|giỏ hàng`); every hit must appear in the Glossary `Viết trong tài liệu` column.
- No Japanese term standing alone in a Vietnamese/English sentence.
- UI actions / UI states / IT terms follow `custom/rules/ui-action-wording.md`. Grep the output for `bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng`; every hit outside verbatim quoted screen text must be rewritten with the standard verb, state or English IT term.

Fix every miss before pausing. A term not in the Glossary → ask the user (one question), then add it to the Glossary.

### 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 Inline Comments 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 — no unresolved comment:**
- Gate proceeds normally
- Run telemetry: `ak gate [N] approved --ticket [ticket-id]`
- Continue to next gate

**Exit code 1 — unresolved 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. Run **Mode 3 — Comment Scope & Impact Sweep** below for every comment before telling the user it is done.
5. Tell the user what was updated — the commented line, every other place the sweep changed, and every rule saved for later runs — then ask them to mark the comment thread as resolved in VS Code and type `APPROVED`.

---

## Mode 3: COMMENT SCOPE & IMPACT SWEEP — Never fix only the commented line

> **Why:** A reviewer writes one comment on one line, but the comment almost always states a rule about the whole document. A real case: the comment "bỏ nút *See all winner*" was applied to the row it sat on, while three later rows still had the Tester press that button, and the next generated document brought the button back because nothing remembered the decision. Fixing the commented line alone is not addressing the comment.

Run this for **every** unresolved comment, right after applying the local fix and before reporting back.

### Step 1: Classify the comment

| Scope | Meaning | What it demands |
|---|---|---|
| `local` | Only true for this one line (a typo, a wrong value in this row). | The local fix, nothing more. |
| `document` | States a fact about the feature — an element was removed, renamed, or changed; a value is wrong everywhere. | Local fix **+ impact sweep (Step 2)**. |
| `standard` | States how documents must be written from now on (wording, structure, level of detail). | Local fix + sweep + **persist as a rule (Step 3)**. |

When a comment could be read two ways, treat it as the wider scope. A comment that removes or renames anything is never `local`.

### Step 2: Impact sweep (scopes `document` and `standard`)

1. Extract the concrete keyword(s) the comment is about — the element label, field name, message text, or value (e.g. `See all winner`).
2. Grep every keyword across the **whole** output file and the artifacts it was built from (`AK-Docs/03.Testing/01.Testcases/[functionId]/` for a test case run — TestCase, Test Plan, Review Result, QnA Log), in **all** columns — Pre-condition, Steps, Data Test, Expected Result, Ticket ID, Comment. Include `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md` when it exists: its rows copy test case content, so a removed element survives there unless it is swept too.
3. Resolve every remaining hit one of two ways, never by leaving it:
   - delete the case/step/cell that depends on the removed thing, or
   - rewrite it as a negative case asserting the thing is **no longer there** (e.g. `Section "Recent Hits" không hiển thị nút "See all winner"`).
4. For a test case file, re-run the linter afterwards so a rewrite does not introduce a new violation:
   ```bash
   ak tc lint AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md
   ak tc lint --checklist AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md
   ```
   Deleting a test case during the sweep orphans the checklist rows pointing at it — `--checklist` reports those, and each one is removed with the case it traced to.
5. Report `0 remaining hit` for each keyword. **A sweep that still has hits blocks `APPROVED`** — the CLI cannot see this, so the AI must not proceed on its own.

### Step 3: Persist `standard` comments as project rules

Rules a reviewer states once must survive into the next ticket, otherwise the same comment comes back every run.

1. Append the rule to `AK-Docs/03.Testing/00.Strategies/Review-Feedback-Rules.md` (create the file with a `# Review Feedback Rules` heading and a table if it does not exist):

   | ID | Ngày | Nguồn (gate / ticket) | Rule | Phạm vi áp dụng |
   |---|---|---|---|---|
   | `RF-001` | `2026-09-30` | `Gate 4 — JTS-2325` | Expected Result phải ghi theo từng step, không gộp một khối cho nhiều bước | Mọi bộ TC của dự án |

2. Write the rule as an instruction, not as a report of what happened ("Expected Result phải ...", not "Reviewer nói Expected chưa tốt").
3. Gate 1 of every later `create-testcase` / `create-spec` run reads this file alongside `qa-writing-standards.md` — a rule recorded here is binding from the next run on, with no further prompting.
4. A rule that contradicts a shipped standard is not silently applied: raise it with the user and, if confirmed, update the standard file itself (`qa-writing-standards.md`, template, or skill) so the whole kit follows.

---

## 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 comments file name
- ✅ **ALWAYS** pass the lettered gate (`2a`, `2b`, …) to `ak review check` for Tester Gate 2 sub-phases — never plain `2`
- ❌ **NEVER** create a checkbox review file (`.aiflow/review/gate-N-[ticket].md`) or ask the reviewer to tick a checklist — the gate only waits for APPROVED and resolved inline comments
- ❌ **NEVER** treat a comment as handled after editing only the commented line — classify it and run the impact sweep (Mode 3) first
- ✅ **ALWAYS** report `0 remaining hit` per swept keyword before accepting `APPROVED`; hits left behind block the gate
- ✅ **ALWAYS** run the terminology self-check (Step 2b) before every gate pause — output terms must match earlier documents and the Glossary
- ✅ **ALWAYS** record a `standard`-scope comment in `AK-Docs/03.Testing/00.Strategies/Review-Feedback-Rules.md` so the next ticket starts with it
