review-issue
Epic-wide review, the auto-fix loop, and how to distill findings into review-knowledge.md
The defining feature of this skill is an EpicEpicThe largest unit of work, grouping multiple Issues together.See in glossary-wide review.
“Epic-wide” means looking not only at the diff of the Issue currently under review, but also at its parent Epic,
Sub-EpicsSub-EpicA subdivision of an Epic, split by feature area or ownership domain.See in glossary, 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.
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.
A problem that blocks mergingmergeIncorporating the changes from a PR/MR. Difficult to undo once performed.See in glossary. The PR/MR cannot be merged until this is resolved; it becomes a target of the auto-fix loop.
Recorded in the report but does not block the merge. Whether to address it can be decided later.
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.
In short: when the blocker count reaches zero the skill creates a PR/MRPR/MRPull Request / Merge Request. A submission that requests review and incorporation of changes.See in glossary 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.
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).
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.
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.
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.
review-knowledge.md serves as a mechanism to prevent the same problem from being implemented twice.