refute

KO | EN

gitlite — search

#privacy #ui #nlp #c #gemini #list #php #editor #go #api

(★ 9)

A deep, multi-angle, adversarially-refuted code review skill for Claude Code, Cursor, and other coding agents

File Explorer

ZIP Download

- header.svg
- - amplification.md
  - angles.md
  - mode-c-angles.md
  - security-owasp.md
- DESIGN.md
- SKILL.md
.gitignore
CHANGELOG.md
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**A deep, multi-angle, adversarially-refuted code review skill for AI coding agents.** Install it once, then run `/deep-review`.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Jmosier69/refute/main/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://raw.githubusercontent.com/Jmosier69/refute/main/)

![refute](https://raw.githubusercontent.com/Jmosier69/refute/main/assets/header.svg)

## What a finding looks like

**Illustrative, not a literal historical transcript.** The mechanics (a finder proposes a claim, an independent refuter tries to knock it down, only survivors get reported) are real and described in full in `SKILL.md` §7. This specific finding is a constructed example, not a pasted transcript.

A `concurrency` angle agent flags this hunk in a credit-redemption endpoint:

> **Finding:** `redeemCredit()` reads the user's balance, checks `balance >= cost`, then writes `balance - cost` in a separate statement. Two requests arriving close together can both pass the check before either write lands.
> **Confidence:** 70 · **Impact:** 75. Breaks a core feature under normal use, not just an edge case.

Before that finding is ever reported, an independent refuter agent gets *only the claim* (never the finder's reasoning) and tries to knock it down:

> **Refuter:** Confirmed. `balance` is read via `GET`, decremented in application code, then written back via `SET`; no `WATCH`, no transaction, no optimistic lock. Two concurrent `POST /redeem` requests reproduce it directly: `ab -c 2 -n 2 http://.../redeem`.

**→ CONFIRMED.** Reported with the concrete failure scenario attached: not "this looks unsafe," but the exact interleaving that breaks it and a command that reproduces it.

If the refuter can't reproduce the claim, or thinks it's wrong, the finding is dropped or marked **PLAUSIBLE** instead of reported as fact. That refutation pass (not the finding itself) is the actual point of this skill.

## What is this

`deep-review` is a comprehensive, multi-angle code review skill for AI coding agents: a `SKILL.md` file that packages a full review pipeline of up to 14 independent review "angles" (correctness, security, concurrency, contracts, test coverage, spec-conformance, and more), each finding scored by confidence × impact, then adversarially refuted before it's ever reported to you. It adapts to four different situations (a mid-flight increment, a pre-merge gate, a sweep across recently-merged PRs, or a security-only pass) rather than being one fixed checklist.

## Why this exists

I built this after running six overlapping code-review skills side by side and realizing each one had one or two genuinely good ideas buried in a lot of redundancy, and, worse, one of them was silently shadowing a better built-in review and downgrading it. `deep-review` absorbs the best parts of all of them into one adaptive pipeline, plus a few things none of them did: checking whether a change delivers a *usable* capability (not just what the ticket literally asked for), flagging silently-reverted code even when nothing asked for it to stay, and never re-litigating a finding you've already rejected.

The full design record (what was absorbed from where, and the reasoning behind every non-obvious decision) is in [`deep-review/DESIGN.md`](./deep-review/DESIGN.md).

## How it works

| Mode | What it reviews | Base |
|---|---|---|
| **A: increment** (default) | Your current uncommitted + in-flight changes | merge-base with `origin/main` |
| **B: pre-prod gate** (`--pr [N]`) | A full PR before it merges | `origin/main` |
| **C: integration sweep** (`--sweep`) | The union diff of everything merged since a marker: do independently-merged PRs still agree with each other? | merges since marker |
| **D: security-only** (`--security`) | Any of the above, security/concurrency/contracts only, at max depth | n/a |

Every applicable angle runs in parallel, each finding is scored (confidence × impact, with a mode-specific floor), and survivors go through independent adversarial refutation. In the pre-merge gate (Mode B, plus anywhere you pass `--amplify`), each finding that survives is then **amplified**: an agent restates the defect as an abstract rule and goes looking for other instances of it — the other six fields on the same model, the other branch of the same conditional, the same rule mirrored at a layer where the semantics differ. A defect fixed in one place is routinely still live one field over, and nobody re-greps for their own bug. Siblings are scored and refuted like anything else, not trusted for being siblings.

The result gets reported: CONFIRMED or PLAUSIBLE findings only, ranked, and separated into three axes that are never reranked against each other (spec-side, standards-side, sibling). Full mechanics, every angle brief, and the exact scoring gates are in [`deep-review/SKILL.md`](./deep-review/SKILL.md).

## Install

Copy or symlink the [`deep-review/`](./deep-review) folder into wherever your agent loads custom skills from.

**Claude Code (confirmed):**

```
git clone https://github.com/Jmosier69/refute.git
cp -r refute/deep-review ~/.claude/skills/deep-review
# or symlink it, if you'd rather track updates:
ln -s "$(pwd)/refute/deep-review" ~/.claude/skills/deep-review
```

Then just run `/deep-review` (or `/deep-review --pr 42`, etc.) inside Claude Code.

If you symlinked, you're tracking `main` — what changed and when is in [`CHANGELOG.md`](./CHANGELOG.md), dated and tagged.

**Cursor, Kimi Code, Codex, and others:** my own workflow is to keep the skill in one place and symlink it into whatever config file each agent expects. Exact directory conventions vary by tool and version, so this repo doesn't hardcode a path that might be wrong for your setup. Point your agent's skill/rule loader at `deep-review/SKILL.md`. **PRs pinning down the exact install path for a specific agent are welcome**, see Contributing.

## Usage

| Command | Mode |
|---|---|
| `/deep-review` | Review your current increment |
| `/deep-review --pr 42` | Pre-merge gate on PR #42 |
| `/deep-review --sweep --since v1.2.0` | Integration sweep since a tag/ref |
| `/deep-review --security` | Security-only pass |
| `/deep-review --fix` | Apply CONFIRMED findings (Modes A/B only), then re-review the fix itself |
| `/deep-review --amplify` | Also hunt for siblings of each confirmed finding (already on in Mode B) |
| `/deep-review --pr 42 --no-amplify` | Skip the sibling hunt in Mode B |
| `/deep-review --min-impact low` | Override the mode's default impact floor |

### Flags reference

| Flag | Values | Effect | Details |
|---|---|---|---|
| `--pr [N]` | a PR number, or omitted to use the current branch's PR | Switches to Mode B (pre-prod gate) | `deep-review/SKILL.md` §1 |
| `--sweep [--since <ref\|date>]` | a git ref, tag, or date | Switches to Mode C (integration sweep) | `deep-review/SKILL.md` §1 |
| `--security` | n/a | Switches to Mode D (security-only, max depth) | `deep-review/SKILL.md` §1 |
| `--fix` | n/a | Applies CONFIRMED findings (Modes A/B only), then re-reviews the fix itself — and, in Mode A, amplifies the findings it fixed | `deep-review/SKILL.md` §12 |
| `--amplify` | n/a | Turns sibling amplification on in Modes A, C, and D. Already on in Mode B | `deep-review/SKILL.md` §8 |
| `--no-amplify` | n/a | Turns sibling amplification off in every mode, including the Mode A `--fix` path. Beats `--amplify` if both are passed | `deep-review/SKILL.md` §8 |
| `--min-impact` | `critical` `high` `medium` `medium-low` `low` | Overrides the mode's default impact floor | `deep-review/SKILL.md` §6 |

## Tested on

I run this myself, as the last step of my own coding process, right before I believe a change is ready for a pull request: not a demo, a daily tool. It's been run end-to-end, personally, on:

- **Claude Code**
- **Cursor**
- **Kimi Code**
- **Pi**, wired to DeepSeek Pro, an unusual combination called out specifically because it's the strongest evidence this isn't Claude-specific: it works against a non-Anthropic model too, not just Claude-family ones

It has **not** been run on Codex yet. The pipeline is plain markdown with no Claude-specific runtime dependency in most of it, so it should work, but "should" isn't "confirmed." If you run it on Codex or another agent, a PR reporting back (or fixing whatever breaks) helps everyone else looking at this repo.

## Cost, read before running

This is not cheap. A full Mode B (pre-merge gate) run is roughly **65-95 agent calls**: 14 angle agents, ~30 scorers, ~11 refuters, plus sibling amplification (one agent per confirmed finding, and a scorer and refuter for each sibling it turns up). Amplification accounts for roughly 25-35 of those and is the part you can turn off with `--no-amplify`, which puts you back at 40-60. Its ceiling is bounded and knowable before you run: confirmed findings × 5.

**Don't run this if you're not on at least a Max-tier plan (or your API budget isn't a concern).** It's built to be the *last* gate before a PR, run once you already believe the code is ready, not a first-pass linter you run on every save. That's also why amplification defaults on only in Mode B: Mode A runs mid-flight and has to stay cheap and quiet, so it costs nothing extra unless you pass `--amplify`.

## Customize to your stack

A lot of what I build runs on Laravel, so a few of the built-in "detector" checks (in `deep-review/SKILL.md` §9) are Laravel/Blade/Alpine.js-specific quirks I've actually hit (real, not hypothetical). They sit under a heading that says so, and they're there as worked examples of the shape a detector takes — they just won't fire on a non-Laravel codebase, which is most of what I run this on anyway. That section is designed to be edited: fork it, or contribute your own.

Detectors and suppressors that were only meaningful inside one codebase have been stripped out rather than shipped. A suppressor in particular is an instruction to your reviewer to stay quiet about something, and one derived from someone else's environment is worse than no suppressor at all.

Spec discovery (§3) checks whatever issue-tracker MCP servers you have connected (Jira, Linear, ClickUp, Asana, GitHub Issues, etc.) rather than assuming one; it works with whatever you've already wired up.

## Design philosophy

- **Advisory only, never blocking.** This emits a verdict; it never acts on one. A false positive must never be able to block a good merge.
- **Never re-litigates a finding you've already rejected.** Dismissals persist outside the repo (`~/.claude/projects/<project>/reviews/`, never committed; a findings history in the codebase is a roadmap for anyone with read access).
- **A fix is not automatically trusted.** `--fix` re-reviews the fix diff itself before accepting it; a fix that introduces its own confirmed defect gets reverted, not shipped.
- **A finding is one instance of a rule.** Where amplification is on, every confirmed finding gets searched outward for its siblings, and the search is forbidden from using the finding's own wording — searching the phrasing you already have only ever finds what you already found. A sibling that lands outside your diff is reported, never auto-fixed, and never blocks a merge — it's a defect in code your change didn't touch. One that lands *inside* it is just an ordinary finding, with full standing: which agent found it doesn't change what it is.
- **On Claude Code specifically, this never escalates to a stronger model automatically.** When a finding is genuinely contested, the review stops and prints a ready-to-paste prompt for you to run that escalation yourself, in a context you control, rather than silently spawning it. (This one behavior assumes a Claude-model-tiered setup; if you're running this on a different agent, adapt or ignore it; see Contributing.)

Full reasoning for every non-obvious decision (including what was deliberately *not* built) is in [`deep-review/DESIGN.md`](./deep-review/DESIGN.md).

## Contributing

I built this for myself because nothing else was exactly what I wanted, and I'm sharing it because someone with enough experience to be looking for a code review skill in the first place is exactly the kind of person who'll want to tweak it. Fork it, strip it, retune the model table, adapt the Claude-specific bits for your agent of choice: MIT means you don't need permission for any of that.

If you get this running cleanly on Codex, Cursor, or Kimi Code and want to document the exact install path, or you tune the detectors for a different stack, PRs are welcome.

## License

MIT, see [`LICENSE`](./LICENSE).

refute

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README