---
slug: "review-forge"
source_type: "skill_md"
source_url: "https://cdn.jsdelivr.net/gh/vikingmute/review-forge@main/SKILL.md"
repo: "https://github.com/vikingmute/review-forge"
source_file: "SKILL.md"
branch: "main"
---
---
name: review-forge
description: Use when orchestrating a code review workflow across multiple LLMs or agents, synthesizing review findings, producing checklist-driven fix scopes, applying selected fixes, running regression tests, independently verifying fixes, updating review status, or keeping code review process artifacts isolated under code_review/.
---

# Review Forge

Review Forge runs a conservative, feature-scoped code review workflow:

1. Inspect the target diff and project context.
2. Create one review file per model or agent inside the current feature folder.
3. Synthesize multiple model review files into a human-controlled checklist.
4. Fix only checked and confirmed items.
5. Run focused and regression tests after every fix batch.
6. Verify fixes independently when possible.
7. Update machine-readable status and localized report labels.
8. Keep all workflow artifacts isolated from product code.

## Commands

- `review`: create one model-specific review file. Do not modify product code.
- `synthesize`: merge model review files from one feature folder into one summary checklist. Do not modify product code.
- `fix`: read checked summary items, confirm the selected scope, implement only those items, run tests, and update status.
- `verify`: verify fixed items with an independent perspective, rerun or inspect tests, and update verification status.

Legacy mode aliases are supported:

- `review-only` means `review` unless the user asks to merge existing review files, then it means `synthesize`.
- `review-and-fix` means `fix`.
- `review-verify` means `verify`.

If the user does not specify a command, infer the safest command from the request. When ambiguous, default to `review`.

## Inputs

Resolve or ask for these inputs before doing work:

- `target`: branch, commit range, pull request, or current working tree.
- `base`: comparison branch or ref. If omitted, infer it using the default diff rules below.
- `artifact_root`: default `code_review/`.
- `feature`: feature name used as the artifact subfolder. If omitted, infer from branch name, PR title, changed package, or a short sanitized summary of the diff.
- `feature_dir`: default `code_review/<feature>/`.
- `command`: `review`, `synthesize`, `fix`, or `verify`.
- `model`: model or agent name for a review file, such as `codex`, `opencode`, `cursor`, `claude`, or `gemini`.
- `report_language`: default `auto`, meaning follow the user's prompt language. Explicit values such as `en`, `zh-CN`, or `ja` are allowed.
- `auto_fix_allowed`: default `false` unless the user explicitly asks to fix.
- `perspective`: optional review focus, such as correctness, security, maintainability, tests, or UX.
- `test_command`: optional override for validation.

## Default Diff Rules

When the user does not specify a target or base, infer the review scope in this order:

1. If the working tree or index has uncommitted changes, review the uncommitted diff.
   - Inspect both unstaged and staged changes.
   - Treat this as `target: working tree`.
   - No base branch is required unless additional context is needed.
2. If there are no uncommitted changes, review the current `HEAD` against `main`.
   - Prefer a merge-base comparison such as `main...HEAD` when supported.
   - If `main` does not exist, try `master...HEAD`.
3. If neither `main` nor `master` exists, inspect branch tracking metadata or PR metadata when available.
4. Ask the user for `base` only when no reasonable comparison ref can be inferred.

Explicit user-provided PRs, branches, commit ranges, or base refs always override these defaults.

## Required Initial Inspection

Before producing artifacts or modifying code, inspect:

- repo status and uncommitted changes;
- target diff against the chosen base;
- existing `code_review/` feature folders and review artifacts;
- `.gitignore` for `code_review/`;
- package, build, and test configuration;
- project-specific instructions for tests, lint, typecheck, or CI.

Never revert unrelated user changes. If `code_review/` is not ignored, recommend adding it to `.gitignore`, but do not edit `.gitignore` unless the user asks.

## Artifact Layout

Group every workflow by feature:

```text
code_review/<feature>/
  <model>.md
  <model>-<perspective>.md
  summary.md
  fix-plan.md
  verify.md
  status.md
```

Rules:

- One model review pass should produce exactly one review file.
- Name review files with the model or agent name first, for example `codex.md`, `opencode.md`, `cursor.md`, `claude.md`.
- If the same model runs multiple perspectives, append a short perspective suffix, for example `codex-security.md`.
- Do not include timestamps by default. Use stable names so the folder is easy to scan.
- Use timestamps only when preserving multiple historical runs is explicitly requested.

Command output boundaries:

- `review`: create or overwrite exactly one model review file, such as `codex.md`. Do not create `summary.md`, `fix-plan.md`, `verify.md`, or `status.md`.
- `synthesize`: read model review files and create or overwrite `summary.md`. Do not create `status.md`.
- `fix`: read checked items from `summary.md`, create or update `fix-plan.md`, and create or update `status.md` after code changes and tests.
- `verify`: create or update `verify.md` and update `status.md` with verification evidence.

Legacy timestamped names such as `STATUS_20260529.md`, `REVIEW_SUMMARY_20260529.md`, or `CODE_REVIEW_codex_20260529.md` should not be created unless the user explicitly asks to preserve dated historical runs.

Use the templates in `assets/templates/` unless the repository already has a stronger local convention.

## Review Collection

In `review` command, create a single file for the current model or agent. If the user does not provide `model`, infer it from the host when obvious; otherwise use a clear name such as `codex`.

For multi-model workflows, each model should run `review` separately and write into the same `feature_dir`. Use distinct perspectives when helpful:

- correctness and edge cases;
- security and data safety;
- tests and regression risk;
- maintainability and architecture;
- product or UX behavior when relevant.

Each finding must include severity, evidence, affected files, risk, and a concrete suggested fix. Avoid vague style preferences unless they affect maintainability or user-facing behavior.

## Synthesize Command

In `synthesize` command, read review files from one `feature_dir` and produce `summary.md`:

- select all model review files in the folder by default;
- exclude `summary.md`, `fix-plan.md`, `verify.md`, and `status.md`;
- merge duplicate findings;
- preserve meaningful disagreement;
- record reviewer agreement count;
- include suggested tests;
- use checkboxes for human fix approval.

Checkbox semantics are stable:

- unchecked: not approved for fixing;
- checked: approved for fixing.

Do not fix unchecked issues opportunistically.

## Fix Rules

In `fix` command:

1. Read `summary.md` from the selected `feature_dir`.
2. Select only checked items whose status allows fixing.
3. Confirm the fix scope unless the user already explicitly approved it.
4. Create or update `fix-plan.md`.
5. Modify only the files needed for selected items.
6. Run tests.
7. Update `status.md` and, when appropriate, the summary status fields.

If a checked item reveals a larger issue, stop and ask before expanding scope.

## Test Rules

Tests are mandatory after fixes unless impossible.

Run validation in this order:

1. The narrowest relevant test for the touched behavior, when discoverable.
2. Typecheck, lint, or build checks relevant to the touched files.
3. The broader project regression command when discoverable and reasonably scoped.

If tests cannot be run, record:

- status enum `test_blocked`;
- the command that should have run;
- the blocking reason;
- residual risk.

If tests fail, do not claim the item is fixed or verified. Mark affected items `verification_failed` or `partially_fixed`, record the failing command, and summarize the failure.

## Verification Rules

In `verify` command:

- verify from a perspective independent of the fixer when possible;
- check whether each selected issue was actually addressed;
- rerun or inspect test evidence;
- look for regressions caused by the fix;
- update status only when evidence supports it.

Verification requires either passing test evidence or a clear `test_blocked` explanation.

## Language Policy

Write skill instructions, template field names, and machine-readable status enums in English.

Generated prose reports should use `report_language`:

- `auto`: follow the user's prompt language;
- explicit language values: write prose in that language;
- keep status enums in English even inside localized reports.

Status display labels may be localized.

## Status Enums

Use these exact machine-readable status values:

- `open`
- `approved_for_fix`
- `fixed`
- `partially_fixed`
- `wont_fix`
- `risk_accepted`
- `verified`
- `verification_failed`
- `test_blocked`

Each status entry should include both:

- `status`: one enum above;
- `status_label`: localized human-readable label, for example `Fixed ✅` or `已修复 ✅`.

## Completion Criteria

A Review Forge workflow is complete only when:

- review artifacts are under `feature_dir`;
- checked items are the only fixed items;
- test evidence or `test_blocked` rationale is recorded after fixes;
- verification status does not overclaim;
- process artifacts remain isolated from product code.