agentleFS
shawnclyborshawnclybor/clybor-claude-tooling/.claude/skills/adversarial-review/SKILL.md

adversarial-review

Skill6 starsChanged 29 days agoMITView on GitHub

Coordinated three-lens adversarial review of any target — a PRD, a build plan, a validation report, code, or a freeform proposal. Spawns chaos-engineer, simplifier and adversarial-reviewer in parallel against non-overlapping questions, grades every finding against a rubric fixed BEFORE the agents run, defers the machine-decidable classes to a mechanical checker, and tracks the review process's own drift across runs so it cannot ratchet indefinitely. Use when a proposal, plan or document needs adversarial scrutiny before it is committed to. Triggers — "adversarial review", "review this plan", "tear this apart", "what's wrong with this", "review before I commit", "/adversarial-review". Do NOT use for a routine code diff (use code-review) or a build plan's pre-execution gate (use build-validate, which this complements rather than replaces).

111 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use rethink, root-cause-analysis and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • fabioespindulaSkill

    rethink

    Reframe a plan, idea, or decision before the user commits to it. Use when the user asks to rethink, step back, pressure-test, gut-check, decide, right-size, simplify, think bigger about, or evaluate a concrete plan or decision in product, strategy, technical architecture, career, life, company direction, or personal priorities. This skill improves decision quality before action: clarify the real question, challenge assumptions, compare alternatives, calibrate ambition, classify the operating mode, surface risks, and recommend a next move. Do not use for broad future exploration without a concrete decision; that belongs to a think-big or research-style skill.

    Also in 3 projects that use this

  • MicrosoftSkill

    root-cause-analysis

    Use when a Regional Retail Manager asks I'm seeing unusual inventory movement at our Northwest stores. Can you help me understand what's happening?

    Also in 3 projects that use this

  • anasahmed07Skill

    better-auth-best-practices

    Skill for integrating Better Auth - the comprehensive TypeScript authentication framework.

    Also in 4 projects that use this

  • DockerSkill

    fix-issue

    Fix a single GitHub issue end-to-end: triage, research, write the fix, review, and create a PR. Use when asked to fix an issue: "fix issue 1234", "resolve #500", "create a PR for issue 200".

    Also in 3 projects that use this

  • MicrosoftSkill

    pull-request

    Write concise, focused pull request descriptions for Wassette — at most three sentences on the what and why, with an explicit note on any breaking public-API change and how users adapt. Use when opening or editing a Wassette pull request.

    Also in 3 projects that use this

  • juriwiensSkill

    codex-review

    Run code review via Codex CLI

    Also in 3 projects that use this

  • +1 more from microsoft

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 100 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read rubric.md in this skill's directory.

    line 24
  2. Distinctive:

    Do not restate the rubric in agent prompts from memory — paste it.

    line 28
  3. Distinctive:

    If it reports drift, surface that to the user before running the panel and ask whether to proceed.

    line 59
  4. Distinctive:

    Every agent prompt must carry these four constraints verbatim:

    line 68
  5. Distinctive:

    Name the class: Every must-fix names which of false-pass / wrong-deliverable / wasted-days it causes, concretely.

    line 72
  6. Distinctive:

    A tracked open question is not a defect: If the target records something as undecided *and* names who decides it and when, that is a plan, …

    line 76

“Common” is measured: kept by at least 6 in 10 of the 100 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adversarial Review

Three lenses, one fixed rubric, a machine doing the machine-decidable part, and a check on whether the review itself is still measuring anything.

Why this exists

A review process with no written rubric and no stop condition does not converge. It ratchets. The failure is documented: one build plan reviewed four times in a day, each round clearing ~30 findings and introducing 2-3, the must-fix count rising 9 → 46 while the plan grew 47 → 60 tasks and zero product code was written. The findings were mostly real. The process was broken — four different hunting instructions reported as one running total, no severity threshold, self-inflicted defects counted as pre-existing, and no definition of done.

This skill exists to make that visible while it is happening rather than in a post-mortem.

Phase 0: LOAD THE RUBRIC — before anything else

Read rubric.md in this skill's directory. It defines must-fix, the three lens boundaries, what the mechanical checker owns, and the stop condition. It is loaded before the target is read, so severity is a property of the finding rather than of the mood of the round.

Do not restate the rubric in agent prompts from memory — paste it. A paraphrased rubric is a different rubric.

Phase 1: CLASSIFY THE TARGET + RUN THE MECHANICAL GATE

Identify the target type. It sets the lens emphasis, and the emphasis is fixed per type — the same type gets the same questions every run.

Target typeDetect byLens emphasis
build plan.claude/PRPs/*/plan.md, or a task list with DONE checkschaos: sequencing + fail-open · simplifier: task count vs requirement · adversarial: DONE falsifiability
PRD.claude/PRPs/*/prd*.md, or success criteria + anchor casechaos: criteria that cannot fail · simplifier: scope beyond the ask · adversarial: unsourced claims, criteria that measure the wrong thing
validation reportvalidate.md, evaluate.md, a findings listchaos: findings that cannot be acted on · simplifier: duplicate findings · adversarial: severity inflation, re-grades
codea source file or diffchaos: inputs, boundaries, error paths · simplifier: over-abstraction · adversarial: does it do what it claims
freeformanything elsethe three base questions unmodified

Then run the mechanical checker if one applies. For a build plan:

python3 .claude/hooks/check-plan-soundness.py <plan> --prd <prd>

If it fails, stop and fix that first. Those defects cost seconds mechanically and an hour with agents. Do not spend a panel on them.

Phase 2: DRIFT PRE-CHECK

python3 .claude/hooks/review-drift.py check <target>

If it reports drift, surface that to the user before running the panel and ask whether to proceed. A fourth round on an unchanged target usually should not happen; the answer is to build the thing, not to look harder. Running the panel anyway is a decision the user makes knowingly.

Phase 3: THREE LENSES, PARALLEL, ONE MESSAGE

Spawn all three in a single message. Each gets: the full rubric text, the target, its own column from the lens table, and the exclusions.

Every agent prompt must carry these four constraints verbatim:

  1. Your lens only. A finding outside your column is not yours — drop it, do not report it. Three agents reporting one finding is three counts of one problem.
  2. Name the class. Every must-fix names which of false-pass / wrong-deliverable / wasted-days it causes, concretely. If you cannot, it is a note.
  3. These classes are already machine-checked and clean — do not re-report them: <paste the checker's class list from rubric.md>.
  4. A tracked open question is not a defect. If the target records something as undecided and names who decides it and when, that is a plan, not a gap.

Give each agent the previous round's findings where a history exists, with: "Findings already accepted and fixed. Do not re-report. If you believe one was fixed wrongly, say so explicitly as a regression — that is different from finding it again."

Phase 4: SYNTHESIS — dedup, classify, count honestly

  • Deduplicate across lenses. One defect = one finding, whichever lens found it first.
  • Re-grade every claimed must-fix against the rubric yourself. Agents inflate. The synthesis step is where the rubric is actually enforced, not the agent prompts.
  • Count self-inflicted findings separately. A defect introduced by the previous round's fixes is real and must be fixed, but it is not the target degrading, and folding it into one total is how a report says "46" when it means something else.
  • Note contradictions between lenses rather than resolving them silently.

Phase 5: RECORD + VERDICT

python3 .claude/hooks/review-drift.py record <target> \
  --must N --should N --note N --self-inflicted N
python3 .claude/hooks/review-drift.py check <target>

Report:

## Adversarial review: {target}   (round N)

Rubric: rubric.md (unchanged since {date} | CHANGED this run — see below)
Mechanical gate: PASS/FAIL
Drift: none / {signals}

### Must-fix (N)     — each names false-pass / wrong-deliverable / wasted-days
### Should-fix (N)   — does not block
### Note (N)         — recorded once, not re-litigated
### Self-inflicted (N of the must-fix, introduced by the previous round)

### Verdict
{PASS — zero must-fix} / {FAIL — N must-fix} / {STOP — cap reached, build instead}

Stop condition

Review is done when the checker passes, must-fix is zero, and the last round produced no new must-fix classes. Cap: three rounds. A fourth needs a written reason naming what changed about the target or the rubric — pass it as --round-note. Absent that, the honest verdict is STOP: remaining doubt gets resolved by building and running, not by re-reading.

Guidelines

  • Read-only. This skill never edits the target. It reports; the human decides.
  • Do not edit the target while the panel runs. Findings against a moving file arrive already cured or already stale — observed, twice.
  • Changing the rubric is allowed and must be explicit. Edit rubric.md, say so in the report, and expect the count to move for that reason alone. A silent standard change is the drift.
  • Complements build-validate, does not replace it. build-validate is the pre-execution gate for a plan with a profile and a mirror. This is the general-purpose lens set, usable on anything, and the one to reach for outside the build pipeline.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.