harness-review

Harness Review

Harness integration review skill. This SKILL.md is a thin dispatcher; for detailed quality criteria, read references/ .

if $ARGUMENTS == "": → Interpret as "review of work done so far" and execute Review target detection → Auto-start only when the review target can be narrowed down to one → If the review target is unknown or there are multiple candidates, present options with AskUserQuestion, align understanding, then start

Output Contract (P35: countermeasure for the "looks stopped" UX)

At skill conclusion, the output's last 1 linemust always include the following literal:

↑この結果は Claude が要約します。Enter キーで次へ進むか、新規 prompt で別の指示を出してください。

This is <local-command-stdout> This is an explicit instruction (patterns.md P35) for the UX problem where the user feels it has "stopped" when displayed as a text response via .

Dispatcher Contract

This skill's responsibility is only review judgment. It does not perform commit / push / release by default.

review default read-only boundary: default is read-only.APPROVE does not auto-commit either
Do not push just to review: do not push for review purposes only
If a commit is needed, delegate to an explicit user request,harness-work, or harness-release 's Work Commit Gate
--commit-on-approve Until an explicit opt-in such as is designed, default side effects for this skill alone are prohibited

Quick Reference

Command	Mode	Purpose
`/harness-review`	`code`	Auto-detect and review work done so far
`/harness-review --quick`	`quick`	Lightly close out a small dirty change
`/harness-review --codex-closeout`	`codex-closeout`	Close out with Codex advice + focused tests
`/harness-review --dual`	`dual`	Claude + Codex second opinion
`--pre-review cursor`	`code+pre-review`	fresh-context composer advisory pre-review before brain verdict（read-only）
`/harness-review --cursor`	`code+cursor-second-opinion`	core review gates + cursor second-opinion (brain primary review required)
`HARNESS_IMPL_BACKEND=cursor harness-review`	`code+cursor-second-opinion`	Even when default ON, automatically add cursor second-opinion to core review gates. primary verdict is fixed to brain
`/harness-review --team-debate`	`team-debate`	Force TeamAgent Debate
`/harness-review --security`	`security`	security-only review
`/harness-review plan`	`plan`	`Plans.md` plan review
`/harness-review scope`	`scope`	scope creep / omission review

Mode Decision

Determine the execution mode from the arguments, and select and load the necessary references/ .

Input	mode	References to read
No arguments / `code`	`code`	`references/code-review.md`, `references/governance.md`
`--quick`	`quick`	`references/codex-closeout.md`, `references/code-review.md`
`--codex-closeout`	`codex-closeout`	`references/codex-closeout.md`
`--dual`	`dual`	`references/dual-review.md`, `references/team-debate.md`
`--team-debate`	`team-debate`	`references/team-debate.md`, `references/governance.md`
`--security`	`security`	`references/security-profile.md`, `references/governance.md`
`--ui-rubric`	`ui-rubric`	`references/ui-rubric.md`
`plan`	`plan`	`references/plan-review.md`, `references/governance.md`
`scope`	`scope`	`references/scope-review.md`, `references/governance.md`
`--cursor` or resolver result `cursor` for no-arg / `code` review only	`code+cursor-second-opinion`	`references/code-review.md`, `references/governance.md`, `references/cursor-review.md`, `references/dual-review.md`
`full`	`full`	`references/code-review.md`, `references/team-debate.md`, `references/dual-review.md`

quick と codex-closeout is the lightweight path. Quickly review small dirty changes, single commits, and PR branch closeouts. It does not discard quality gates.

Cursor Default ON

When determining the mode, first confirm explicit mode words (plan, scope, full) and explicit flags. For no-arg / code review only, resolve the helper root, run the resolver exactly once, and when the resolver is absent, claude is regarded as such.

HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"; if [ -z "$HARNESS_PLUGIN_ROOT" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ]; then probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"; while [ "$probe" != "/" ] && [ ! -d "$probe/scripts" ]; do probe="$(cd "$probe/.." && pwd)"; done; [ -d "$probe/scripts" ] && HARNESS_PLUGIN_ROOT="$probe"; fi
if [ -x "${HARNESS_PLUGIN_ROOT:-}/scripts/resolve-impl-backend.sh" ]; then resolved_backend="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh" --role reviewer)"; else resolved_backend="claude"; fi

no-arg / code review, if the result is cursor , add the same --cursor as cursor-second-opinion , but always read the core review gates (references/code-review.md, references/governance.md) first, and treat Cursor references only as additive. Keep the primary verdict on the brain side, and limit cursor to the advisory of dual_review.cursor_verdict .plan / scope Explicit mode words such as take precedence over the resolver result, and cursor default does not replace either plan/scope references or code/governance references. If the result is claude / codex , it is as before, and the primary judgment surface of the review is not changed.

Pre-Review Cursor (`--pre-review cursor`)

/harness-review --pre-review cursor は bash scripts/pre-review-cursor.sh [--base ref] で read-only fresh-context composer pre-review（model-routing.sh --host cursor --tier review → cursor-companion.sh task、--write / --workspace / --resume (without ) once, andPRE_REVIEW_FINDINGS: is attached to the brain primary review input. companion failure is PRE_REVIEW_SKIPPED + exit 0（fail-open）。verdict is brain only(self-review scope contract).

Review Target Detection

REVIEW_AUTOSTART contract: When called with no arguments ($ARGUMENTS == ""),review / /review / /harness-review only input is interpreted as "review of work so far". As a handshake line before starting Step 1, output only the following single line.

REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode}

REVIEW_TARGET_ASK contract: When the review target is unknown or there are multiple candidates on a bare call, before proceeding to Step 1, use AskUserQuestion exactly once to narrow the candidates to 2-3 and confirm.

Candidates are created in the following order.

working tree: only uncommitted changes including staged / unstaged / untracked
branch range: commits from upstream or main/master to HEAD
recent commits: the most recent 1 commit / most recent 5 commits when branch range cannot be obtained with a clean tree

When multiple candidates hold simultaneously:

REVIEW_TARGET_AMBIGUOUS: working_tree_and_branch_commits

AskUserQuestion candidates:

Uncommitted changes only (Recommended): compare staged / unstaged / untracked against HEAD
View everything: view branch base..HEAD and uncommitted changes together
Commit only: view only the committed work of branch base..HEAD

When the tree is clean and there is no branch diff:

REVIEW_TARGET_AMBIGUOUS: clean_tree_no_branch_commits

AskUserQuestion candidates:

Most recent 1 commit (Recommended): HEAD~1..HEAD
Most recent 5 commits: HEAD~5..HEAD
Another range: wait for a user-specified ref

After the user's answer:

REVIEW_TARGET_CONFIRMED: {choice}
REVIEW_AUTOSTART: target={resolved_target}, base_ref={resolved_base_ref}, type={mode}

Prohibited:

Responding "the task is unclear" and stopping
Asking "what should I review?" in free-form text and stopping
Skipping auto-start on the grounds of the host project's session-start rules
Broadening the scope by guessing even though the target is ambiguous

Minimal Flow

decide the mode
decide the target and base ref via the above Review Target Detection
read only the necessary reference
diff, untracked files, related tests, specification source of truth,Plans.md check
APPROVE / REQUEST_CHANGES / decision_needed return
REQUEST_CHANGES in the case of , indicate the critical / major fix policy and the post-fix re-review conditions

Review Governance Contract

For details, see references/governance.md. Here, only the minimum pass line is fixed.

Clear pass line

APPROVE is returned only when all of the following are satisfied (for details, see references/governance.md）。

0 critical / major items
root spec.md alignment (does not contradict the product contract; specification source of truth alignment check required)
Plans.md alignment（task / DoD / Depends、[lane:*], stage gate matches the contract)
TDD evidence（[tdd:required] は tdd_red_log / failing output / skip_tdd_reason）
unknown data contract（not_observed != absent — do not APPROVE "no problems" / "no data" without evidence)
regression safety (no degradation in existing behavior, tests, UX, CLI, settings, docs, mirror)
- If you grep the same symbol twice in the same session, switch to harness_ast_search.
- For a bugfix where homologous implementations appear across multiple modules, run harness_ast_search to find all implementations before editing.
- Only when changed files include .ts or .tsx, the DoD requires zero new harness_lsp_diagnostics errors; if the harness MCP is not connected or the changed file types are not eligible, treat diagnostics as not-configured and non-blocking.
evidence pack (accepted / rejected findings, focused tests, release-preflight warnings handling)
No unresolved TeamAgent Debate disagreement

APPROVE is not a commit / push / PR creation command (read-only boundary).

TeamAgent Debate

For details, see references/team-debate.md. TeamAgent Debate is a review pass that makes different viewpoints collide in a read-only manner.

Agent	Main questions
Spec Agent	Look for contradictions between the specification source of truth and the implementation diff
Plans Agent	`Plans.md` Check the correspondence between the task / DoD / Depends of and the diff
Regression Agent	Look for regressions in existing behavior, tests, distribution mirrors, and CLI/skill UX
Skeptic Agent	Look for major risks overlooked under the assumption of wanting to pass

Even if native TeamAgent is unavailable in the Codex environment, this gate must not be omitted. codex-companion.sh review, reproduce the same 2-4 viewpoints with an available reviewer subagent, or with an explicitly separated read-only manual pass, andteam_agent_mode に native / codex-companion / manual-pass / unavailable record .

Code Review Summary

For details, see references/code-review.md. A normal code review looks at the following.

Security
Performance
Quality
Accessibility
AI Residuals
Spec Alignment
Plans Alignment
Regression Safety
TDD compliance

root spec.md For details on alignment, Plans lane/stage, TDD evidence, unknown data contract, and evidence pack, references/governance.md と references/code-review.md。

AI Residuals は scripts/review-ai-residuals.sh と scripts/review-weak-supervision-report.sh should be used preferentially. If you also want to look at untracked files, --include-untracked use . mockData, dummy, fake, localhost, TODO, FIXME, it.skip, test.skip, expect(true).toBe(true) etc. are candidates, and severity is decided in the diff context. The finding stage prioritizes comprehensiveness. Even findings judged as minor should be left in observations[] / recommendations[] , and the gate is performed only at the verdict stage (Opus 4.8 has a tendency to narrow down low-severity reports.references/code-review.md See Finding coverage in ).

Quick / Codex Closeout Summary

For details, see references/codex-closeout.md。

Principles of the lightweight path:

Fix target selection first
Treat Codex findings as advisory, and decide acceptance after confirming with the actual code
Include review command / tests / accepted findings / rejected findings / clean result in the final report
stop-on-clean: after a clean result, do not perform additional reviews just for appearance
If Codex is unavailable, fall back to a full manual pass, and do not treat failure as success

helper:

bash scripts/harness-review-closeout.sh --dry-run --uncommitted
bash scripts/harness-review-closeout.sh --base origin/main --parallel-tests --test "bash tests/test-harness-review-governance.sh"
bash scripts/harness-review-closeout.sh --commit HEAD

Plan Review Summary

For details, see references/plan-review.md。 Plan Review は Plans.md Look at the DoD / Depends / Status of and the implementation order. For tasks that require a specification source of truth, if spec_path does not exist,decision_needed stop as .

Scope Review Summary

For details, see references/scope-review.md. Scope Review looks at whether the boundaries of requirements, diffs, tests, and docs are expanding. If a scope change is needed, do not proceed by guesswork; return to AskUserQuestion or a plan update.

Security / UI / Dual

Security: references/security-profile.md
UI rubric: references/ui-rubric.md（--blind-judge Can be used together: an opt-in second opinion that is OFF by default. A fresh sub-agent that is given neither a rubric nor a prior verdict — context: fork not allowed. The target is only external-facing UI copy / docs / cognitive-load HTML surfaces; code, tests, config, and schemas are not allowed,advisory only (verdict unchanged). For details and eligibility, see ${CLAUDE_SKILL_DIR}/references/blind-judge.md）
high-res vision flow: references/vision-high-res-flow.md
Dual review: references/dual-review.md

/ultrareview is not called by default within the Harness flow. This is because it does not replace the connections with the Harness flow's review-result.v1, commit guard, and sprint-contract. claude ultrareview [target] --json is treated only as a second opinion from CI / script.

PR Host Boundary

GitHub-first. Review facts on the PR host are taken as authoritative from GitHub, and the local diff is treated as supplementary evidence. However, local uncommitted reviews are not pushed to GitHub.

Output Contract

User-facing prose follows the explicit session or project language. If no language is configured, use English. Use Japanese only when i18n.language: ja, CLAUDE_CODE_HARNESS_LANG=ja, or an explicit session instruction requests Japanese output. Machine-readable values stay English.

Start with the result summary.

## Review Result

### {APPROVE | REQUEST_CHANGES | decision_needed} - {one-line conclusion}

Target: `{BASE_REF}..HEAD` or `{target}`
Verification: {commands run}

Strengths:
- ...

Findings:
- [severity] file:line - issue and evidence

Next Actions:
- ...

Details:
```json
{
  "schema_version": "review-result.v1",
  "verdict": "APPROVE | REQUEST_CHANGES",
  "decision_needed": {
    "required": false,
    "ask_tool": "AskUserQuestion"
  },
  "accepted_findings": [],
  "rejected_findings": [],
  "acceptance_bar": {
    "critical_major_zero": true,
    "spec_alignment": "pass | fail | not_applicable",
    "plans_alignment": "pass | fail | not_applicable",
    "regression_safety": "pass | fail | not_applicable",
    "verification_evidence": "pass | fail | not_applicable"
  },
  "team_debate": {
    "required": false,
    "mode": "native | codex-companion | manual-pass | unavailable",
    "team_agent_mode": "native | codex-companion | manual-pass | unavailable",
    "agents": [],
    "disagreements": []
  },
  "critical_issues": [],
  "major_issues": [],
  "observations": [],
  "recommendations": []
}
```

Codex Environment

In the Codex environment, the available tools differ, but the pass line, the spec source of truth,Plans.md, regression, post-fix re-review, AskUserQuestion / decision_needed.v1 contracts are the same.

Normal environment	Codex fallback
Task tool の TeamAgent Debate	reviewer subagent / `codex-companion.sh review` / manual-pass
AskUserQuestion	If unavailable, `decision_needed.v1` is output to stdout, and do not proceed on guesswork
TaskList	`Plans.md` read directly

Related Skills

harness-work: REQUEST_CHANGES post-fix execution
harness-plan: plan / scope / spec updates
harness-release: commit / release of reviewed work