---
title: review-issue
description: >-
  Epic-wide review, the auto-fix loop, and how to distill findings into
  review-knowledge.md
seo:
  image: /ogp.png
---
**The defining feature of this skill is an <Tooltip tip="The largest unit of work, grouping multiple Issues together." headline="Epic" cta="See in glossary" href="/glossary">Epic</Tooltip>-wide review.**
"Epic-wide" means looking not only at the diff of the Issue currently under review, but also at its parent Epic,
<Tooltip tip="A subdivision of an Epic, split by feature area or ownership domain." headline="Sub-Epic" cta="See in glossary" href="/glossary">Sub-Epics</Tooltip>, and sibling Issues (other Issues that share the same parent).
The review also loads the shared-context pack (the set of files containing shared team assumptions), and in
particular `review-knowledge.md`, before proceeding.

:::note[This skill is what creates PR/MRs]
`implement-backlog` commits code but does not create a PR/MR. Creating the PR/MR is the responsibility of
`review-issue`, and only when the blocker count reaches zero. If implementation is complete but no PR/MR
is visible, it means this skill has not been run yet. See [the status-label state machine](/concepts/status-labels)
for details.
:::

## Command and main options

```
/architect:review-issue [item] [--epic=<id>] [--max-fix-rounds=N] [--base=<branch>] [--no-fix] [--dry-run] [--auto] [--lang=en|ja]
```

| Option | Meaning |
|---|---|
| `item` | The review target. Specified as `I1.2.3`, `#<iid>`, or a URL. If omitted, items with `status::doing` / `status::review` are picked up and confirmation is requested. |
| `--epic` | Narrow the target to a specific Epic. |
| `--max-fix-rounds=N` | Maximum number of auto-fix loop iterations. Default is 3. |
| `--base` | Base branch for the PR/MR. |
| `--no-fix` | Output review results only; do not run the auto-fix loop. |
| `--dry-run` | Report what would be created without actually creating the PR/MR. |
| `--auto` | Skip intermediate confirmation prompts. |
| `--lang` | Output language for comments and reports. |

## The three severity levels

Every finding is assigned one of three severity levels. The level determines what happens next and whether
action is required.

**[B] blocker**

A problem that blocks <Tooltip tip="Incorporating the changes from a PR/MR. Difficult to undo once performed." headline="merge" cta="See in glossary" href="/glossary">merging</Tooltip>. The PR/MR cannot be merged until this is resolved; it becomes a target of the auto-fix loop.

**[S] important**

Recorded in the report but does not block the merge. Whether to address it can be decided later.

**[Q] question**

A question the reviewer noticed. No action is required.

## Auto-fix loop

When a blocker is found, the skill repeats a "fix → re-review" cycle until the blocker is resolved, subject
to a maximum number of iterations.

```mermaid
flowchart TD
  A[Run review] --> B{"Blockers present?"}
  B -- No --> C["Create PR/MR"] --> D["status::review"]
  B -- Yes --> E["Delegate to fix sub-agent (Agent tool)"]
  E --> F["Re-review (round+1)"]
  F --> G{"Limit reached (default 3) or no-progress?"}
  G -- No --> B
  G -- Yes --> H["status::blocked + ask user to decide"]
```

In short: when the blocker count reaches zero the skill creates a <Tooltip tip="Pull Request / Merge Request. A submission that requests review and incorporation of changes." headline="PR/MR" cta="See in glossary" href="/glossary">PR/MR</Tooltip> and moves to the
next stage. If the iteration limit (default 3) is reached without resolution, or if the same problem fails to
be fixed in two consecutive rounds (no-progress), processing stops, the item is set to `status::blocked`, and
a human is asked to decide.

## How findings are distilled into `review-knowledge.md`

The raw record of findings from each round is preserved as-is in
`reports/backlog/reviews/review-<issue>-round<N>.md`. In addition, `[B]` (blocker) and `[S]` (important)
findings are also preserved through a process called *distillation*. Distillation means extracting from the
detailed record only the general rules (`KN-<n>`) that are likely to apply to other Issues as well. If an
entry for the same rule already exists, only the `occurrences` field is updated — no duplicate entries are
created.

<Accordion>
  <AccordionItem title="KN-1: Client-supplied actor/owner fields can be spoofed">
    Values such as `ownerId`, `changedBy`, and `role` can be freely specified by the client side. Without
    authentication, these values can be spoofed (overwritten by an impersonator).
  </AccordionItem>
  <AccordionItem title="KN-2: No authentication or authorization exists anywhere on the endpoint">
    There is no authentication (identity verification) or authorization (permission checking) anywhere. This
    is treated not as a single-Issue problem but as a persistent gap (a hole that remains open indefinitely)
    spanning the entire Epic.
  </AccordionItem>
  <AccordionItem title="KN-3: Many-to-many join tables require a uniqueness constraint">
    A join table representing a many-to-many relationship requires a uniqueness constraint (a setting that
    prevents duplicate combinations from being inserted). Without it, data corruption is easy to trigger, as
    demonstrated by the actual duplicate bug encountered in `TeamMembership`.
  </AccordionItem>
  <AccordionItem title="KN-4: Foreign-key reference parameters should be existence-checked symmetrically across sibling services">
    When a foreign key (a reference value pointing to another piece of data) is received, its existence must
    be verified. If only one of several related (sibling) services performs this check, the result is an
    asymmetric security hole present on only one side.
  </AccordionItem>
</Accordion>

`review-knowledge.md` serves as **a mechanism to prevent the same problem from being implemented twice**.