---
name: review-plan
description: Gate 4 — After AI generates code, the developer reviews source code + summary. Developer must provide APPROVED or report a bug before closing the task.
keywords: review, code review, approve, summary, checklist
---

# Review Plan — Gate 4

> ⚠️ **Skip this gate for `gen-doc` tasks.** gen-doc tasks only use Gates 1 and 2 (Gate 2 includes self-review automatically). This gate applies to `feature`, `bug-fix`, `refactor`, `documentation`, and `investigation` tasks.

> **GATE 4: Runs after AI has completed code generation.**
>
> Principle: AI self-reviews first (verification + impact-analysis), then presents a summary to the developer. The developer decides: APPROVED or report a bug.

---

## Conditions to enter Gate 4

- ✅ Gate 1 (requirement doc) has been APPROVED
- ✅ Gate 2 (implementation plan) has been APPROVED
- ✅ AI has completed code generation (Gate 3)
- ✅ `superpowers:verification-before-completion` has run — tests pass
- ✅ `impact-analysis` skill has run

## Mode Selection

Check `mode` in `.aiflow/context/current.json`:

| Mode | Impact Analysis | summary.md |
|------|----------------|-----------|
| `fast` | Quick scan — reason from diff only | Short format |
| `full` | Full grep scan across codebase | Full format |

### Fast Track Impact Analysis (mode: fast)
Assess impact by reasoning about the changed files only:
1. List each file you modified
2. For each file: "Does this file have callers/dependents outside the ticket scope?"
3. If yes → list them and assign impact level
4. DO NOT run grep on the full codebase

## Fast Mode Output Rules (CRITICAL)

When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fast mode**:
- **Do not write long explanations or descriptions.**
- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.

**Example summary.md block:**
```markdown
### Gate 3 — Code
- ✅ **Implemented batch endpoints**
  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
```

---

## Process

### Step 1: AI self-review (before showing the developer)

Run in the following mandatory order:

```
1. superpowers:verification-before-completion
   → All tests must PASS. If any fail → fix immediately, do not show the developer.

2. impact-analysis skill
   → Check for breaking changes and side effects.
```

**If any step fails → fix first, do not proceed to Step 2.**

### Step 1.5: Design Conformance Check (UI tickets only)

If `plan/[ticket-id]/design/design-context.md` exists, compare the generated UI against the
design — **visually against the rendered reference image, not just the text checklist.** Open
`public/assets/figma/_reference-<nodeId>.png` (or the Figma frame) and the running UI, and check
region by region (header / panel / sections / footer):

- [ ] **Reference image compared** region by region; every visible difference listed
- [ ] **Background** is the correct layer (paint order) and actually visible
- [ ] **No-fabricate**: no element rendered that isn't in the design (no extra button/section)
- [ ] **No-omit**: every text label + every image node is present in its region
- [ ] Layout matches (arrangement/position per region, not a generic flow)
- [ ] Colors match the Design Tokens table (project token or arbitrary value)
- [ ] Typography matches (size, weight, line-height)
- [ ] Every component listed in "Components to build" exists
- [ ] Every image in the Image Map exists under `public/assets/figma/`

Any mismatch → treat as a coding bug: fix before Step 2. A text-only checklist tick is NOT enough —
if you have not actually looked at the reference image, say so. Skip this step for non-UI tickets.

### Step 2: Create Summary Report

Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:

```markdown
# Summary: [Ticket ID] — [Title]

**Date:** [YYYY-MM-DD]
**Status:** Waiting for DEV review

---

## Implementation Details

| File | Change | Reason |
|------|----------|-------|
| [path/to/file] | Created / Modified | [reason] |

---

## Acceptance Criteria — results

| Criteria | Status | Notes |
|---------|--------|---------|
| [Criteria 1] | ✅ Done | [implementation details] |
| [Criteria 2] | ✅ Done | |

---

## Tests Written

| Test file | Test cases | Coverage |
|-----------|-----------|---------|
| [file] | [N] cases | [X%] |

**Test output:**
```
[Paste test results here]
```

---

## Impact Analysis results

**Level:** 🟢 Low / 🟡 Medium / 🔴 High

**Impact Scope:**
- [File/Service A] — [reason for impact / lack of impact]

**Breaking changes:** None / [description if any]
```

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

### Step 2.5: Retrospect + propose memory drafts

Synthesize what was learned this task. **Priority order — human corrections first:** if this is a repeat pass through Gate 4 (the developer already sent "BUG: ..." at least once this task), the developer's own correction is the single highest-value lesson — scan back through this session for it and draft it even if you already drafted something for the earlier BUG at Step 4 (dedup will catch an exact repeat; don't skip capturing it out of caution). Only after that, add anything else genuinely new: architecture facts discovered, decisions made and why. For each candidate, create a **local draft** (no approval needed yet — `_pending/` is local-only, doc `docs/common/Memory-Architecture-v1.0.md`):

```
ak memory draft --category 01.Lessons/dev --function-id [functionId] \
  --slug <short-kebab-slug> --content "<≤150 từ, 1 fact>" \
  --tags <tag1,tag2> --workflows coding --source "[ticket-id] / Gate 4"
```

Other useful categories here: `00.Shared/architecture` (facts about the system discovered while coding), `00.Shared/decisions` (a technical choice made and why). Skip this step if nothing genuinely new was learned — don't manufacture a memory just to have one.

If `ak memory draft` reports a conflict (a similar memory already exists), don't create a duplicate — mention it to the developer instead so they can decide whether to edit the existing one.

List the created draft(s) in the Step 3 message below so the developer knows what's sitting in `_pending/` — they (or anyone on the team) can inspect and `ak memory submit` it later when ready to share with the team.

### Step 3: GATE 4 — Present to Developer

```markdown
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️  GATE 4: WAITING FOR DEV REVIEW

I have completed implementation and self-review.
Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md

**Self-review results:**
- Tests: ✅ [N] passed / ❌ [N] failed  
- Impact: [Low/Medium/High]
- Memory drafts created: [N] (local, `_pending/` — `ak memory submit` when ready to share)

**You need to:**
1. Review the summary above
2. Check the source code if necessary
3. Run manual tests if desired

**After review, reply with one of the following:**

✅ If OK: type **"APPROVED"**
🐛 If there are bugs: type **"BUG: [description]"**
   → If a requirement bug: I will return to Gate 1
   → If a coding bug: I will fix and repeat Gate 4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Step 4: Handle feedback

**If the developer types "APPROVED":**
→ Invoke `superpowers:requesting-code-review` to send for peer review
→ Guide on creating a Pull Request

**If the developer types "BUG: [description]" — coding bug:**
→ **Immediately draft a memory** capturing exactly what the developer flagged and why it was wrong (`ak memory draft --category 01.Lessons/dev --function-id [functionId] --slug <slug> --content "<the bug + the fix>" --workflows coding --source "[ticket-id] / Gate 4 dev feedback"`) — do this before fixing, while the correction is fresh; don't wait for Step 2.5 on the next pass to catch it in hindsight.
→ Analyze bug, fix, rerun verification
→ Repeat from Step 1 of Gate 4

**If the developer types "BUG: [description]" — requirement bug:**
→ **Immediately draft a memory** (same category/command as above) capturing what was misunderstood about the requirement and what it actually should have been — this is a requirement-comprehension lesson, valuable even though Gate 1 itself has no retrospect step of its own.
→ Notify: "This is a requirement bug, requirement document needs update"
→ Return to Gate 1, update requirement.md, wait for APPROVED again

---

## Mandatory Rules

- ❌ **DO NOT** invoke `requesting-code-review` before the developer provides APPROVED
- ❌ **DO NOT** decide "task is done" on your own — must be confirmed by the developer
- ✅ **MUST** run verification + impact-analysis before showing the developer
- ✅ **MUST** clearly classify: requirement bug vs coding bug
- ✅ **MUST** update summary.md each time changes are made