adversarial-review

name	adversarial-review
description	Run an on-demand adversarial review of an already-written PRD or Plan with an available local provider.

Adversarial Review

Use this skill only from the existing post-commit PRD review gate or the Plan execution handoff. The caller supplies the task-id and target (prd or plan); the user chooses only whether to review and which available reviewer to use.

Read .superharness/config.yaml. When review.mode is off, return to the caller without showing a review option. The supported first-phase values are off and on-demand.

Inputs and Boundaries

• Require a task-id and a target of prd or plan from the calling workflow. Derive every other runtime argument yourself.
• Identify the current host as codex, qoder, claude-code, or unknown. Do not ask the user for the host.
• The user chooses only whether to start review and one displayed reviewer. Never expose target, host, round, timeout, schema, prompt, session, or rebuttal CLI parameters.
• Do not mechanically validate model identity. Provider capability and authentication probes are the availability boundary.
• This skill is self-contained. Do not read a prompt, schema, or other attachment from this skill directory at runtime.

Provider Menu

Run:

superharness review providers --host {host}

Parse its JSON result. Use providers as the complete menu and preserve the returned Codex > Qoder CLI > Claude Code order. The command has already filtered for installed, compatible, authenticated providers and excluded the current host. Do not add unavailable providers, probe failures, or the current host to the menu.

Show only each returned displayName. After the user chooses one, retain its id as {provider-id} for every round. If providers is empty, show only the returned installHint and return to the calling gate. The host-specific hints are:

• Codex host: Qoder CLI.
• Qoder host: Codex CLI.
• Claude Code or unknown host: Codex CLI or Qoder CLI.

Never recommend Claude Code when no reviewer is available.

If provider discovery fails, show its concrete error and let the user continue without review or retry later.

Context Contract

Start each round with:

superharness review run --task {task-id} --target {target} --provider {provider-id}

The CLI constructs the reviewer context and passes all file locations as absolute paths. Do not construct a second prompt or attach additional files.

• PRD context contains only prd.md, contract.md, and the original requirement summary from workflow:start.
• Plan context contains only plan.md, prd.md, contract.md, and every .superharness/spec/*/index.md as absolute paths sorted by path.
• Do not pass task.json as reviewer context.

Each CLI invocation launches a read-only, stateless, fresh session. Use the full structured result for decisions; any shortened user display must retain finding ids, summaries, evidence, and failure reasons. The CLI ledger retains complete output.

User-Facing Result

Whenever a round is shown to the user, render the structured result instead of dumping CLI JSON. Translate labels into the user's current language while preserving provider ids, finding ids, severity values, and failure codes. Omit sections that do not apply.

Use this shape for a revise result:

### PRD adversarial review — revision required
- Reviewer: Codex
- Round: 1
- Summary: The payment failure path has no verifiable acceptance criteria.

Findings:
- [high] F1 — Missing payment failure behavior
  - Evidence: prd.md defines only the successful payment result; contract.md has no rejected-payment assertion.
  - Recommendation: Add the rejected state, user-visible result, and matching acceptance criterion.

For approved, keep Reviewer, Round, and Summary, followed by Findings: none. For failed, keep Reviewer and Round, then show:

Failure:
- Reason: invocation-failed
- Detail: provider invocation timed out

Do not hide a finding because it will be accepted automatically. After applying accepted findings, state which finding ids were applied and which target files changed. During a rebuttal round, show the reviewer position and drafting-model response in the same structure before reporting convergence or requesting user resolution.

Resolve a Round

Handle the returned result by status:

• approved: report the provider and summary, then return to the calling user gate.
• failed: show failure.reason and failure.detail. Invalid or unparsed output never counts as approval. Let the user continue without review or retry later.
• user-decision: apply the user-decision procedure below.
• revise: inspect every finding against the current documents before choosing the accept or reject branch.

If at least one finding is supported, use the accept branch for the supported set and report any remaining disputed findings to the user at the calling gate. Use the automatic reject branch only when no finding is accepted, so a document edit cannot reset the round state during a rebuttal sequence.

Accept Findings

Accept a finding only when its claim and evidence are supported by the current documents. Apply the smallest coherent correction:

• For target prd, update prd.md and synchronize contract.md. Compare the PRD H1 before and after the edit; update task.json.title only when the PRD title changed. Do not change other task metadata.
• For target plan, update only plan.md. Do not modify prd.md, contract.md, or task.json.

Self-review the changed documents, stage only the files allowed above, and commit the accepted revision. Do not re-review accepted findings. Return to the calling gate so the user can review and approve the revised document.

Reject Findings

Reject a finding only with explicit evidence from the current documents and a concrete drafting-model response. Serialize the disputed finding or findings into the three required rebuttal strings: finding, evidence, and response. Invoke the same provider with the original command plus --rebuttal <json>; never switch providers mid-review.

Every rebuttal invocation uses the same provider in a fresh session. Treat the returned round as authoritative and repeat only while the reviewer maintains the disagreement and round is below 3. Reviewer withdrawal or approval ends the review and returns to the calling gate.

Three-Round Limit and User Decision

Automatic review has a maximum of three rounds across the initial review and rebuttals. When round 3 still returns revise, stop immediately. Do not invoke a fourth round.

Persist the halt before asking for a decision:

superharness review halt --task {task-id} --target {target}

Show the reviewer finding and the drafting model rebuttal side by side, including their document evidence, then ask the user to choose which position governs the document. Do not call the provider again.

If the user accepts the reviewer position, apply and commit the same target-specific edits first. After the edit succeeds, persist the final decision against the resulting document:

superharness review resolve --task {task-id} --target {target} --choice reviewer

If the user accepts the drafting model rebuttal, leave the documents unchanged and persist that decision:

superharness review resolve --task {task-id} --target {target} --choice author

The halt and resolution commands derive the provider, round, document hash, and user actor from the ledger. Never expose these command parameters as user choices. Return to the calling gate after the resolution succeeds.