Adversarial Review

Adversarial Review

Use Pi's adversarial_review tool to run a second-pass, read-only implementation audit with a separate reviewer model inside Pi.

This is for implementations.

• Use the-fool for challenging plans before code exists.
• Use grill-me when the user wants questioning and design pressure-testing.
• Use normal inline review only for light checks.
• Use this skill when the user wants the toughest audit before shipping.

Workflow

1. Gather only what is missing

Figure out:

1. Target directory

• Default to the current working directory when the user is clearly referring to the current repo.
• Ask only if the target is unclear.

2. Plan or spec file

• Use it if the user gave one.
• If none exists, review for internal consistency and production-readiness.

3. Reviewer model

• Prefer a reviewer model different from the current one when possible.
• Let the tool pick the best available default if the user does not care.

4. Review areas

• If the user gives focused areas, pass them through.
• Otherwise use the default 8 areas from references/prompt-template.md.

2. Run the Pi review tool first

Call adversarial_review with:

• targetDir
• optional planFile
• optional reviewerModel
• optional reviewAreas

The tool normally enforces the right shape:

• separate reviewer model inside Pi
• read-only tools only
• no file edits
• required file:line citations for non-PASS findings

2b. Claude Code fallback / explicit Claude request

If the user specifically asks to "ask Claude", "ask Claude Code", "use Opus", or if the Pi adversarial_review tool returns no grounded report, use Claude Code directly instead of treating the failed tool call as a valid review.

Build the filled prompt from references/prompt-template.md, then run Claude Code headlessly from the target directory with read-only tools:

claude --print --model opus --effort high \
  --add-dir "{{TARGET_DIR}}" \
  --add-dir "$(dirname "{{PLAN_FILE}}")" \
  --tools "Read,Grep,Glob,Bash" \
  --disallowedTools "Edit,Write,MultiEdit,NotebookEdit" \
  "{{FILLED_PROMPT}}"

When intentionally delegating to the Claude-side adversarial-review skill from ~/.agents/skills/adversarial-review, use its headless form:

claude --print --model opus --effort high \
  --add-dir "{{TARGET_DIR}}" \
  --add-dir "$(dirname "{{PLAN_FILE}}")" \
  --tools "Read,Grep,Glob,Bash" \
  --disallowedTools "Edit,Write,MultiEdit,NotebookEdit" \
  "Run /adversarial-review headlessly with: target={{TARGET_DIR}}, plan={{PLAN_FILE_OR_NONE}}, reviewer=opus 4.7, areas=[{{REVIEW_AREAS}}]"

Notes:

• Use --dangerously-skip-permissions only inside disposable/sandboxed worktrees when the user explicitly wants that mode; prefer tool allow/deny lists first.
• If {{PLAN_FILE}} is omitted, omit the second --add-dir and pass plan=none.
• The Claude result is valid only if it contains file:line citations for non-PASS findings. If Claude cannot read files or returns an environment/tooling failure, report that as a failed review, not as implementation findings.

3. Present the result cleanly

Always present:

• Overall verdict — ship / fix-before-ship / significant-rework
• Per-area verdicts — PASS / NEEDS-FIX / BROKEN
• Prioritized fixes — P0, then P1, then P2

Do not flatten or soften the review. Keep the citations.

4. If P0s exist, switch to execution mode

If the review surfaces P0 items, ask whether to fix them immediately. If yes, move straight into implementation work on those items.

Constraints

• Never use write/edit/bash for this review pass unless the user explicitly changes the task from review to implementation.
• Never summarize non-PASS findings without at least one file:line citation per finding.
• Keep the review adversarial and truth-seeking, not encouraging.
• This skill audits implementations, not ideas.

Adversarial Review Prompt Template

Fill in all {{PLACEHOLDERS}} before sending to the reviewer.

---

You are performing an adversarial implementation review. Your job is to find real problems, not validate the work.

BE ADVERSARIAL. Ossie explicitly asked you to find problems. Your value here is truthfulness, not encouragement.

What you are reviewing

• Implementation directory: {{TARGET_DIR}}
• Plan / spec to review against: {{PLAN_FILE}}

(If no plan file: assess internal consistency, correctness, and production-readiness instead.)

How to read

Read actual file contents, not summaries. Open every file that is relevant to a review area. Do not infer what code probably does — read what it actually does. If a path, env var, or config value appears in the code, chase it to its definition.

Verdict categories

For each review area, assign exactly one verdict:

• PASS — No issues found. Implementation matches intent.
• NEEDS-FIX — Issues present but not launch-blocking. Can ship with fixes queued.
• BROKEN — Defect that will cause failures in production. Must fix before shipping.

Review areas

{{REVIEW_AREAS}}

Default areas (use if none specified):

1. Plan fidelity — Does the implementation match the plan/spec? What is missing, misimplemented, or added without justification? 2. Control flow and logic — Are conditionals correct? Are there off-by-one errors, incorrect comparisons, inverted boolean logic? 3. Error handling — Are all error paths handled? Are exceptions caught or propagated correctly? Are partial failure states recoverable? 4. External dependencies — Are env vars validated at startup? Are file paths correct and not machine-specific? Are shell commands safe from injection? 5. Scheduling and timing — Is timing behavior correct? Are timezone assumptions explicit? Are there race conditions between scheduled jobs or async work? 6. Idempotency and state — Can operations run more than once safely? Are there missing deduplication guards? Can partial runs leave corrupted state? 7. Data parsing and serialization — Are parsing failures handled? Are schema assumptions validated? 8. Session and path assumptions — Do file paths work across machines? Are session and cwd assumptions explicit and stable?

Bug classes to hunt

Look specifically for these — they are the most common sources of silent failures:

• Off-by-one bugs in loops, date ranges, array indexing
• Unhandled exceptions that swallow errors silently
• Race conditions between async operations or scheduled jobs
• Missing idempotency guards on operations that repeat
• Incorrect cron syntax or timing assumptions
• Path assumptions that break on a different machine or user home
• Missing env var handling (crash on undefined vs. graceful fallback)
• Shell injection in subprocess calls (unquoted variables, user input in shell strings)
• JSON parse errors from untrimmed whitespace, trailing commas, encoding issues
• Timezone bugs — code uses local time where UTC is expected or vice versa
• PATH assumptions — hardcoded binary paths that break in non-login shells
• Session file location assumptions — files written to cwd instead of stable paths

Required output format

Overall verdict

State one of: ship / fix-before-ship / significant-rework

Justify in 2-3 sentences.

Per-area verdicts

For each numbered review area:

[N. Area Name] — PASS | NEEDS-FIX | BROKEN
Finding: <specific description>
Evidence: <file>:<line> — <quoted or paraphrased code>
Impact: <what breaks and when>

If PASS, one line is enough: [N. Area Name] — PASS

Prioritized fix list

List every non-PASS finding in priority order:

P0 — Blocks launch (will cause failures in production before first use)

• [ ] <Fix description> — <file>:<line>

P1 — Reliability (will cause failures under normal use, not immediately)

• [ ] <Fix description> — <file>:<line>

P2 — Polish (won't cause failures, but degrades quality or maintainability)

• [ ] <Fix description> — <file>:<line>

If a priority level has no items, omit that section.