- All other Preconditions (code files specified, mechanical-green gate green ([org-internal #2598]), checklist accessible) STILL APPLY.
- The `core/checklists/pipeline-gate.md` cross-stage gate (Upstream Review Convergence section) → NOT required; the bugfix-specific Pre-Design Falsification Gate section still applies if relevant.
**DGN dimension handling**: In standalone-bugfix mode, the DGN (Design Compliance & Dependencies) reviewer is SKIPPED because there is no design to comply with. The Orchestrator dispatches 9 reviewers (all 10 dimensions except DGN).
**What standalone bugfix review focuses on**: code correctness, error handling & compatibility (COR), regression coverage (TST), security (SEC), performance (PERF), style & conventions (STY), database & data (DBT), accessibility & browser compatibility (A11Y), documentation (DOC), traceability (TRC) — everything that does not depend on a design baseline.
**Historical**: the legacy pipeline mode (design doc + design-space/plan
review convergence as preconditions) was archived 2026-08-21 ([org-internal #3072] phase 3).
Historical design pages remain readable via `_shared/gitea-read-patterns.md`.
### DAG Task Mode
Triggered for a `Kind/Task` ticket under a DAG-routed parent Epic — the
**Precondition replacements** for DAG task mode (mirror verify's DAG task-mode
table and implement's §"DAG-mode input path"):
| Standard precondition | DAG-task-mode replacement |
| --- | --- |
| Design-space review converged (`octopus review status --stage design-space`) | review-dag single-gate converged: `octopus review status --stage review-dag` must show state `success` (this Epic already passed the single gate; do NOT re-run it). Not converged → abort: "review-dag 未收敛，代码评审无法开始" |
| Iteration-plan review converged (`--stage iteration-plan`) | REMOVED (DAG has no plan review; the single review-dag gate replaces both) |
| `slug` matches the design slug | N/A (review is scoped to the node ticket; run slug = `{epic-slug}-task-{node-id}` — the same node-task run namespace verify's task mode archives to — so review outputs are node-scoped and never clobber sibling nodes' reports. Note: this namespace covers review + verify runs only; the node's implement report below lives in the Epic run workspace `{epic-slug}/workers/` — implement worker runs keep the Epic run slug (implement §Preconditions: "DAG: `{epic-slug}`"), a different run from this review run) |
| `core/checklists/pipeline-gate.md` Upstream Review Convergence | NOT required — the review-dag convergence check above stands in its place |
| All other preconditions (code files specified, mechanical-green gate green ([org-internal #2598]), checklist accessible) | KEEP — unconditional; plus the implement report (AC → test traceability) present — Tier 1 at `<runs-root>/{epic-slug}/workers/{node-id}-worker-{seq}.md` (implement Phase 5 persistence; `{chunk-id}` = the node id) |
The `{BASELINE_SECTION}` for DAG-task mode uses the node spec + cross-session
edge contracts from `{epic-slug}/dag` instead of the design index; the 5-Check
Gate's legacy `{slug}/03-design-index` references resolve to the node's `req_refs` +
component field in `{epic-slug}/dag` (mirror `implement/SKILL.md` DAG-route
read map). The `{READ_FIRST_STEPS}` for DAG-task mode replaces step 1 with:
"Read the node spec + cross-session edge contracts in `{epic-slug}/dag` first
for orientation (plus the `{epic-slug}/dag-nodes/{node-id}` subpage when AC
detail is sunk)."
**Output naming (node-scoped)**: the Tier 1 run dir is
`<runs-root>/{epic-slug}-task-{node-id}/reviews/code/round{N}/` and the
convergence, surface the drift, and let the signal's re-derivation mandate
run (same posture as `frozen_contract_breaking` — no local-fix convergence).
A pure estimation miss (same scope, mildly larger surface) is recorded as
the revision rationale and does not block.
**Record the mode**: commit status context stays `pipeline/review-code`, with
a `mode: "dag-task"` field (as lightweight mode records `mode: "lightweight"`)
— verify's task mode keys off this ticket's review-code PASS.
### Prototype Promotion Mode
Triggered when the `prototype` skill's EVOLUTIONARY contract reaches its promotion gate. The caller passes `mode: "prototype-promotion"`.
**Required inputs**:
-`.artifacts/{slug}/prototype-debt.md`（存量只读，不迁移；Gitea 等效：wiki page `{slug}/prototype-debt`，`_shared/gitea-read-patterns.md` Pattern 1）— the debt register maintained during the evolutionary prototype phase.
- The code files being promoted (same as standard mode).
**Promotion rule**: reviewers MUST treat every line item in the debt register as a review finding unless it has an explicit prior waiver. A debt item without a waiver blocks promotion with severity `MAJOR`. The promotion gate is passed only when the debt register is empty OR every remaining item carries a written waiver added to the register by the reviewer during this review.
**What reviewers focus on in addition to standard dimensions**: the debt register itself — is each promotion criterion concrete and testable, or is it vague ("improve later")? Vague criteria are flagged as DOC findings.
### Lightweight Review Mode (Test-Only Changes)
Triggered when the changeset consists **entirely** of test files (paths matching
`*.test.ts`, `*.test.tsx`, `*.spec.ts`, or `__tests__/**`) with zero source-code
changes outside test files. The Orchestrator MUST verify this condition before
entering lightweight mode: run `git diff --name-only` and confirm every changed
file is a test file.
**Weakened preconditions** for lightweight mode:
- Design doc existence → NOT required.
- Design-space review convergence → NOT required.
- Iteration-plan review convergence → NOT required.
- All Preconditions from the pipeline checklist are bypassed.
- Only requires: the mechanical-green gate ([org-internal #2598]) — same script as the full
mode; on a test-only changeset `test:changed` selects exactly the changed
tests, so the gate cost stays proportional to the diff.
**Reduced review surface**: The Orchestrator dispatches only **1–3 reviewers**
covering the minimum dimensions:
- COR (Correctness): are assertions testing the right thing? No tautological
asserts, no `.not.toThrow()` wrapping a call that never throws.
- TST (Test Quality): coverage completeness, boundary cases, no duplicate
coverage of already-tested paths.
- STY (Style): follows existing test file conventions (describe/it structure,
naming, setup/teardown patterns).
The Orchestrator assembles findings manually (no synthesis sub-agent; one round
only). Lightweight reviews do NOT iterate — if findings exist, the Developer
fixes them and the Orchestrator re-verifies, but does not spawn a second review
round. The review is recorded as round 1 with a `mode: "lightweight"` field in
the commit status (context: `pipeline/review-code`).
**Exclusion rule**: If ANY changed file is a source file (even a one-line fix),
fall back to the appropriate full mode (pipeline or standalone-bugfix).
| Property | Standard (Pipeline) | Standalone Bugfix | DAG Task | Lightweight (Test-Only) |
| Reviewer | Explorer | 10 (risk-tier scaled) | 1 dimension per reviewer at L tier; grouped sweep at S/M tiers (see Risk Tier table; grouped dispatch fills the shared prompt's {DIMENSION_CODE}/{DIMENSION_NAME} with the joined group per `_shared/review-reviewer-prompt.md`). Read-only (9 in standalone-bugfix mode; DGN skipped) |
| Developer | Worker | 1 | Revise code based on synthesis (the same role |
| | | | that wrote the original code) |
All reviewers run in parallel. The orchestrator and developer run sequentially
(orchestrator → developer → orchestrator → ...).
## Risk Tier Assessment (Reviewer Count Scaling)
Before dispatching reviewers, the Orchestrator MUST assess the changeset's risk
tier to determine the optimal reviewer count. This replaces the fixed
1-reviewer-per-dimension model.
### Tier Determination
Run `git diff --stat` to measure the changeset, then classify:
| **S** (Small) | <5 changed files AND single package AND no public API/config change | 1 | All 10 dimensions in a single reviewer sweep |
| **M** (Medium) | 5–15 changed files OR multi-package OR public API change | 3 | Group A: COR+TST+DBT; Group B: DGN+SEC+PERF; Group C: STY+A11Y+DOC+TRC |
> **Findings sink: `tier1-local`** ([org-internal #1988]). `review-code` writes raw
> per-dimension findings to Tier 1 local files (`<runs-root>/{slug}/reviews/code/`),
> not Gitea issue comments. The synthesis comment + commit status stay Tier 2.
> See `_shared/review-pipeline-phases.md` "Output model — two findings sinks"
> and `core/rules/two-tier-artifacts.md`.
---
## Standardized Reviewer Prompt Template
The Orchestrator MUST use the standardized reviewer prompt template at
`core/skills/_shared/review-reviewer-prompt.md` when dispatching each
reviewer. The same template goes to every dispatched reviewer (10 at L tier,
3 at M tier, 1 at S tier); the Orchestrator fills
in skill-level constants (below) and per-dimension values (from the dimension
table).
**Skill-level constants** (same for all reviewers in this skill):
- Model tier: default session reviewer model (`Reviewer` Explorer role, `_shared/roles/reviewer.yaml`) — review-code sets no `reviewer-tier` override (unlike review-dag, which consumes `analyze-dag`'s reviewer-tier); record any assignment change here so sibling review skills stay comparable (TRC 10.5)
(absolute worktree path — see the worktree-path rule below), validated by
`core/schemas/reviewer-output.schema.json`. `review-code` is the first
skill migrated to the Tier 1 findings sink (see `_shared/review-pipeline-phases.md`
"Output model — two findings sinks" and `core/rules/two-tier-artifacts.md`).
The synthesis (human gate) and commit status STAY Tier 2 (Gitea).
---
<!-- section:phase-a -->
## Phase A — Parallel Review
> **Canonical mechanics**: `core/skills/_shared/review-pipeline-phases.md` — keep this section in sync with the canonical Phase A–E flow. This section adds review-code-specific constants (10 dimensions, severity definitions, risk tiers, output mode, standalone-bugfix mode). Step 0 (move source issue to `review` column on Pipeline Stages board per Pattern 7.5) is inherited from the shared Phase A orchestrator actions; see `_shared/review-pipeline-phases.md`.
When invoked from the `implement` skill in bugfix mode (caller passes
`mode: "standalone-bugfix"` — the legacy "detect absence of a design doc"
fallback is retired with the design pipeline, [org-internal #3072] phase 3):
1. The Orchestrator dispatches **9 reviewers** (all 10 dimensions **except DGN** — Design Compliance & Dependencies), because there is no design baseline to audit compliance against.
2. For any dimension that would normally receive design reference files (COR, DGN, SEC, PERF, TST, DBT, A11Y, DOC, TRC), substitute the bugfix baseline docs:
- These replace the design sub-files in `{FILE_SECTIONS}` (the "Design Files for Cross-Reference" section).
3. The `{BASELINE_SECTION}` uses the **Bugfix Baseline** variant (from the constants above), not the Design Baseline.
4. The `{READ_FIRST_STEPS}` replace "Read the design `index.md`" with:
```
1. Read `.artifacts/{slug}/repro-notes.md`（存量只读，不迁移；Gitea 等效：wiki page `{slug}/repro-notes`，`_shared/gitea-read-patterns.md` Pattern 1）first (if it exists) for the bug's root cause and expected behavior.
2. Read every code file listed above. Do NOT skip any file.
3. Read `.artifacts/{slug}/impl-notes.md`（存量只读，不迁移；Gitea 等效：wiki page `{slug}/impl-notes`，`_shared/gitea-read-patterns.md` Pattern 1）(if it exists) for the post-fix behavior contract.
```
5. The `{CONTRADICTION_RULE}` is weakened: code that contradicts repro-notes/impl-notes is a MAJOR — there is no design to elevate to BLOCKER.
6. All other Phase A dispatch rules (reviewer comment posting, commit status, reviewer prompt template, temperature, permissions, worktree-path rule) apply unchanged.
7. Efficiency optimization (round 2+, [org-internal #2598]): follows the shared Phase D rule (`_shared/review-pipeline-phases.md` Phase D "Efficiency optimization") with no standalone-mode deviation — partial re-dispatch, full sweep every 2 rounds, delta-scoped reviewer input.
**Orchestrator actions**:
1. Prepare Tier 1 run workspace: ensure `<runs-root>/{slug}/` exists with a
2. Initialize or update review status by posting a commit status via `POST /api/v1/repos/Octopus/octopus/statuses/{sha}` (`_shared/gitea-write-patterns.md` Pattern 8) with context `pipeline/review-code`. The commit-status payload carries `state` and `description`; the full review lifecycle state is documented in `core/schemas/review-status.schema.json` and tracked by the `octopus review status` CLI.
2.5. **Mechanical-green gate (mandatory, [org-internal #2598])** — before spawning ANY reviewer,
run `bun core/skills/review-code/scripts/precondition-gate.ts {slug} --round {N}`
from the worktree root. Exit 0 → continue to step 3. Exit 1 → the script has
appended a PRECONDITION-BLOCK record (Tier 1,
`<runs-root>/{slug}/reviews/code/precondition-gate.jsonl`); do NOT dispatch
reviewers — dispatch the Developer (Phase C) with the failing check name and
the first error lines, then re-enter this step. A blocked attempt does NOT
increment the review round. On the first gate run, append one `index.json`
row for the gate log (type `precondition-gate`, stage `review-code`,
produced_by `Orchestrator`, `schema: null` — the jsonl is self-versioned
and machine-regenerable, no backing `core/schemas/*.json`) following
the findings-row pattern.
The gate is fingerprint-cached: when the Developer already ran the
pre-handoff gate (Phase C step 4) on the unchanged tree, this step
cache-hits and costs ~nothing — do not skip it.
3. Spawn **all reviewers in parallel** (10 in pipeline mode at Large tier; fewer at Small/Medium tiers; DGN skipped in standalone-bugfix mode). Each reviewer receives:
- The standardized prompt (above) with dimension-specific values filled in.
- For round ≥ 2 ([org-internal #2598] delta scoping): `{FILE_SECTIONS}` lists ONLY the
files revised since the previous round plus their 3–5 convention-comparison
neighbors — not the round-1 full file set. Round 1 keeps the full set.
- Agent type: Explorer.
- Permission: read-only EXCEPT scoped write to the Tier 1 findings dir. Pass
`permissions` with `allow` rules for `read`, `glob`, `grep` (read-only
everywhere) PLUS an `edit` allow for the runs dir so the reviewer can write
its OWN finding file — do NOT pass deny rules (they are inherited). Example:
- Foreground (the Orchestrator waits for completion).
3. The Synthesizer:
- Reads all dimension finding JSONs from
`<runs-root>/{slug}/reviews/code/round{N}/findings-*.json` (in its OWN
context, not the Orchestrator's — no Gitea call).
- Computes synthesis following `core/schemas/synthesis.schema.json`.
- Posts synthesis as an issue comment via `工单评论 API（见 TERMINOLOGY）` （`_shared/gitea-write-patterns.md` Pattern 5）with a ```json code block on the ticket for `{slug}` (Tier 2 human gate — stays on Gitea).
- Updates review status by posting a commit status via `POST /api/v1/repos/Octopus/octopus/statuses/{sha}` （`_shared/gitea-write-patterns.md` Pattern 8）with context `pipeline/review-code`.
— the rendered `## Round-1 Findings Summary` table consumed verbatim by
Phase E step 2.55 (template step 8; shared Phase B step 3 "Round-1
findings digest"; `index.json` row type `review-synthesis`). Rounds ≥ 2
skip this.
- Returns a compact summary (≤ 2KB) with verdict, per-dimension results,
and re-audit targets.
4. The Orchestrator receives the summary and proceeds to Phase C or Phase E
based on `overall_verdict`. The Orchestrator does NOT read dimension JSONs
or the synthesis comment directly — all decision-relevant data is in the
Synthesizer's return summary.
5. Present the Synthesizer's return summary to the user in chat.
---
<!-- section:phase-c -->
## Phase C — Developer Revision
If `overall_verdict` is PASS, skip to Phase E.
Otherwise:
**Orchestrator actions**:
1. Prepare the Developer's input as a structured task file,
created as a wiki page via `wiki 读写 API（见 TERMINOLOGY）` （`_shared/gitea-write-patterns.md` Pattern 1）with page_name `{slug}/reviews/code/round{N}/task-developer`.
This file must contain:
- Paths to all code files that need revision.
- Reference to the synthesis comment on the ticket (posted via `工单评论 API（见 TERMINOLOGY）` in Phase B — Tier 2).
- References to the Tier 1 finding files for dimensions that have FAIL or WARN
3. The Developer revises the code files in place. The Developer creates a
revision summary as a wiki page via `wiki 读写 API（见 TERMINOLOGY）` （`_shared/gitea-write-patterns.md` Pattern 1）with page_name `{slug}/reviews/code/round{N}/revision-summary`,
- "Thanks for catching that!" / any gratitude expression.
- "Let me implement that now" — before verification.
**INSTEAD:**
- Restate the technical requirement concisely.
- State the fix factually: `Fixed {finding-id}: <what changed> at <file:line>`.
- Just fix it and show the result in the diff.
#### Gracefully Correcting a WAIVE
If you WAIVEd a finding and were wrong:
```
"Verified {finding-id} — the reviewer is correct. My initial read missed
<reason>. Implementing now."
```
State the correction factually. No lengthy apology.
#### Implementation Order
For multi-finding revisions, after clarifying all unclear items:
1. **Blocking issues** — security, data loss, breaks existing functionality.
2. **Simple fixes** — typos, imports, naming, dead code.
3. **Complex fixes** — logic changes, refactoring within minimal-surgical scope.
Test each fix individually.
#### Rationalization-Anticipation Quick Reference
| Trap | Hold to |
|------|---------|
| "The reviewer flagged it as BLOCKER, so it must be real." | VERIFY cited code exists and rule applies before any edit. |
| "Just fix everything to avoid a re-review round." | EVALUATE each finding; WAIVE the wrong ones with reasoning. |
| "This finding looks plausible — I'll fix it without checking." | Open the file:line, confirm the behavior. |
| "I'll implement the clear findings and ask about unclear ones later." | STOP. Clarify ALL unclear items before implementing any. |
| "The reviewer wants it done 'properly' — full abstraction." | Check call sites first. If unused, WAIVE (YAGNI). |
| "I shouldn't push back — the reviewer is probably right." | Push back with technical reasoning. The diff is the acknowledgment. |
---
<!-- section:phase-d -->
## Phase D — Re-review Loop
After the Developer completes revision:
1. Increment the round counter (the Synthesizer updates the commit status in Phase B
with the new round's results).
2. Re-enter Phase A at step 2.5 — the mechanical-green gate re-runs on the
revised tree before any reviewer spawn (a red gate blocks dispatch exactly
as on round-1 entry) — then spawn the new round of reviewers against the
revised files.
**Convergence criteria**: see `core/skills/_shared/review-pipeline-phases.md` Phase D for the canonical table (stop conditions). `{MAX_ROUNDS}` is per-skill — code review binds the routing budget: **2** rounds default, **3** for high risk (a BLOCKER survived a round, or the diff touches a frozen cross-session contract) — `<instance-root>/workflow-routing.yaml` `review.max_rounds` ([org-internal #3567]). The code-review-specific addition is inheritance of the shared INFO-disposition rule. The shared Round-3 Escalation Guardrail is scoped to the `review-artifact` skill targets only and does not apply here.
**Round budget (mandatory, [org-internal #3567])**: when `current_round` reaches the budget (2; 3 for high risk) without convergence, do NOT enter another round. STOP: register every remaining BLOCKER/MAJOR finding as TD registry rows (`rules/ticket-lifecycle.md`), record the verdict (FAIL if any BLOCKER remains, else PASS — the debt is carried by the TD registry rows just registered), and close the loop. A review that cannot converge within budget is a design-level stall wearing review clothes (retro 2026-08-21 / [org-internal #3050]): in DAG task mode, map it to the DAG oversize signals (`<instance-root>/workflow-routing.yaml` `dag.size_derivation.oversize_signals`) and let the aggregator agent drive re-derivation + a `review-dag` re-run; otherwise record the design-level finding on the Epic, or open `{slug}/03-design-amendments` via `wiki 读写 API（见 TERMINOLOGY）` (`_shared/gitea-write-patterns.md` Pattern 1).
**Efficiency optimization**: see `core/skills/_shared/review-pipeline-phases.md` Phase D (same rule — from round 2 onward ([org-internal #2598]), only spawn reviewers for FAIL/WARN/UNRESOLVED dimensions; full sweep every 2 rounds). Round ≥2 reviewer input is delta-scoped to the revised files + their neighbors.
1. Create the final report as a wiki page via `wiki 读写 API（见 TERMINOLOGY）` （`_shared/gitea-write-patterns.md` Pattern 1）with page_name `{slug}/reviews/code/final/report`
2. Update review status by posting a commit status via `POST /api/v1/repos/Octopus/octopus/statuses/{sha}` （`_shared/gitea-write-patterns.md` Pattern 8）with context `pipeline/review-code` and `converged: true/false`.
2.5. Ensure the final report wiki page `{slug}/reviews/code/final/report`
All review artifacts: ticket #{issue_number} comments + wiki pages under `{slug}/reviews/code/`（DAG task mode: under `{epic-slug}/reviews/code/`, Tier 1 round artifacts under `<runs-root>/{epic-slug}-task-{node-id}/reviews/code/`）
Inline comments（only when step 2.56 ran；omit for no-PR flows）: `inline: X posted / Y file-level / Z fallback / W failed`
→ Approve and proceed? (yes / no / revise)
```
The `question` tool auto-approves per `core/rules/auto-approve.md` (stage `"review-code"`).
Do NOT advance without approval (auto or explicit).
2.7. **Issue checklist sync (mandatory on PASS).** Only once the verdict is
PASS, the report is finalized, AND the user has approved the final report
(step 2.6 above — if the user instead chose "revise", skip this sync: a new
round runs and the annotation happens on the eventual PASS round), sync the
source issue's checklist per the `issue-checklist-sync` L1 rule — follow
its "How to sync (each point)" procedure (identify source issue → fetch body
→ map → update, preserving non-checklist content) — do NOT wait for the
verify skill:
- Check off review-related items (e.g. "代码评审通过" / "reviewed") and
append `_(reviewed: round {N} PASS)_`.
- The `## 当前状态` review row is written by the `status-sync` poller
(`.gitea/scripts/status-sync-poll.ts`), NOT this skill — do NOT manually
`工单 API（见 TERMINOLOGY）update` the PR / 代码评审 / CI rows (per
`issue-checklist-sync.md` § Automated sync). If no `## 当前状态` section
exists and this is an incident / standalone-bugfix flow, create the empty
section (the poller never creates it); the poller then populates the PR
and review rows.
2.8. **Update the `## 工件索引` comment** (artifact index — Pattern 10). If
the source issue has an artifact index comment, update it in place per
`_shared/gitea-write-patterns.md` Pattern 10: add/update a `REVIEW-code`
row with 位置 = `{slug}/reviews/code/final/report`, 重读 = `CORE`
(DAG task mode: row id `REVIEW-code-task-{node-id}`, 位置 =
`{epic-slug}/reviews/code/final/report-task-{node-id}` — per the
Pattern 10 per-skill row map). If no index comment exists yet, create
one following Pattern 10's
creation + per-skill row map. Do NOT create a duplicate index comment
— check for the legacy prefix `## Pipeline 工件追踪表` first per
`core/rules/artifact-index-guards.md`.
---
## Orchestrator Rules (Mandatory)
See `core/skills/_shared/review-orchestrator-rules.md` for the mandatory
