ai-diff-reviewer

AI Diff Reviewer — Local & CI Companion Skill

The **AI Diff Reviewer** is a GitHub Action that runs an LLM review on every pull request in CI. This skill is its local counterpart — the same reviewer, driven by your coding agent (Cursor, Claude Code, Codex, Gemini, Copilot, Cline, Windsurf, Grok CLI, Pi, OpenCode), on the branch you're editing right now. It also installs and configures the CI Action itself when your repo doesn't have it yet.

Two audiences, same skill.

• If your repo already runs the Action in CI → use the skill

locally to catch what CI would catch, seconds before pushing. When CI is wired to the same extension file (prompt-extension-file: .review/extension.md), local and CI reviews match — same base prompt, same overrides. See the "Parity guarantee (Flow B)" section below for the wiring details.

• If your repo doesn't have the Action yet (or you don't want it)

→ the skill still gives you the full review locally, AND — when you're ready — helps you install the Action in CI with sensible defaults for strictness, triggers, and external-contributor policy.

Five coordinated capabilities, routed by intent:

Sub-skill 3 (setup) also doubles as the reference manual for every action.yml input via `setup/reference.md` — any agent can answer "what does `strictness` do?" without opening the action source.

Version parity. The `prompt.md` in this skill is byte-identical to the one the Action ships in the same tagged release (enforced by CI's Skills — prompt-sync invariant job). Pinning @v2.1.0 on both surfaces guarantees the same methodology and severity model (CI may additionally dedupe on round 2+ via Iteration-Aware Review; local reviews stay a full pass).

Source: <https://github.com/DailybotHQ/ai-diff-reviewer> · License: MIT

Two supported flows: local-only or dual-surface

The five sub-skills are independent. There is no ordering requirement, and installing the CI GitHub Action is NOT a prerequisite for using this skill locally. Every consumer repo falls into one of two flows — pick the one that matches the repo's use case:

Parity guarantee (Flow B). When setup writes the workflow with prompt-extension-file: .review/extension.md wired in (default when you accept the Step 5 handoff to generate-extension), the CI Action reads the same file your local agent uses. Same base prompt + same extension file = same review methodology and severity model, locally and in CI. CI may still post a shorter finding set on round 2+ of a generation because Iteration-Aware Review dedups there (local reviews never do — see below). If the Step 5 handoff is declined, setup omits prompt-extension-file and you get base-prompt parity only — you can add the input manually later, or re-run setup and accept the handoff.

CI-only surfaces (not mirrored locally). Three Action capabilities run only in GitHub Actions, not in this skill's local review flow (locally the review runs on whatever model your coding agent already uses — the Action's provider/api-base choice and its usage telemetry do not apply):

1. Iteration-Aware Review (IAR) — content-anchored dedup across

rounds, four convergence policies (default first-pass-exhaustive), escape label (full-review-please), and user-forced reset (remove applied-label then re-trigger). A local review is always a full pass against the current diff — it may surface findings CI has already deduped on round 2+ of the same generation. Spec: `docs/ITERATION_AWARENESS.md`. Tuning example: `examples/iteration-aware.yml`.

1. `skip-review-label` emergency bypass — when the configured

label is on the PR, CI short-circuits to success with no LLM call. Hotfixes / rollbacks only; protect the label with a ruleset. Spec: `docs/TRIGGER_MODES.md` § Emergency-bypass. Example: `examples/skip-review-label.yml`.

1. Incremental follow-up rounds + usage telemetry (v2.1.0+) — on

rounds 2+ CI reviews only what changed since its last review plus its own still-open findings (resolution claims are advisory; a maintainer resolves the thread — or, since v2.3.1, the runtime retires a corroborated fix whose thread collapse-previous already minimized), and every CI review ends with a **Usage:** line (tokens, cache hit rate, turns, cost). A local review is a full pass with no usage line. Spec: `docs/ITERATION_AWARENESS.md` § 14.

The full input reference (including every IAR knob and skip-review-label) lives in `setup/reference.md`.

Signalling the flow to your agent. If the ambiguous request "set up the reviewer" could mean either flow, the agent will ask. To skip that question, be explicit the first time in each repo:

• Flow A: "Set up ai-diff-reviewer for local-only use — do NOT install the GitHub Action."
• Flow B: "Full ai-diff-reviewer setup — install the Action workflow AND generate the extension file."

Every subsequent request in the repo ("review my branch", "open the PR", etc.) works identically across both flows — the flow distinction only matters at first-time setup.

Install

# Latest v2.x
npx skills add DailybotHQ/ai-diff-reviewer --skill ai-diff-reviewer

# Or pin to a specific tag for reproducibility
npx skills add DailybotHQ/ai-diff-reviewer@v2.1.0 --skill ai-diff-reviewer

This vendors the skill into .agents/skills/ai-diff-reviewer/ in the consumer repo and records source + content hash in skills-lock.json so any teammate can restore identical bytes with npx skills experimental_install. Bump to the latest with npx skills update ai-diff-reviewer.

Note on the git repo slug. The repo path stays at DailybotHQ/ai-diff-reviewer (historical — published tags from v1.0.0 onward, current major @v2). The --skill ai-diff-reviewer flag matches the Marketplace listing name; both refer to the same product.

Activation

The frontmatter description carries only the compact routing summary (hosts cap it at 1,024 characters); the full trigger catalogue lives here and is authoritative for routing.

Default flow (run a review) — triggers:

• "Review my current branch"
• "Run a code review on my changes"
• "Do a pre-flight review before I push"
• "Code review the diff against main"
• "What would CI say about my current commits?"

Generate-extension flow — triggers:

• "Generate a .review/extension.md for this repo"
• "Customize the code review for our project"
• "Help me write repo-specific review rules"
• "Tailor the reviewer to our stack"

Setup flow (install the GitHub Action) — triggers:

• "Set up AI Diff Reviewer for this repo"
• "Configure the reviewer action"
• "Install the AI Diff Reviewer GitHub Action"
• "Help me create the pr-review workflow"
• "How do I add AI Diff Reviewer to this project?"
• "How do I set up ai diff reviewer?" (any casing)
• Also fires as the answer to reference-style questions about the

action — "what does `strictness` do?", "how do I use `label-gate`?" — via `setup/reference.md`.

Open-PR flow (author the pull request) — triggers:

• "Open the PR", "create a pull request for this branch"
• "Draft the PR title and description"
• "Write the PR body"
• "Update the PR description", "rewrite the PR body in the proper format"
• "Make a draft PR" (adds --draft)

Apply-review flow (read + apply the CI review on the PR) — triggers:

• "What did the CI review say?"
• "Read the review on this PR", "show me the review findings"
• "Apply the AI review's fixes", "walk me through the findings"
• "Help me address the critical findings", "critical only"
• "Which findings blocked the merge?"
• "The bot posted a review — help me address it"

If the trigger is ambiguous (e.g. developer says "help me with the review" on a repo that has no .review/extension.md yet, or says "handle the PR" on a repo where a PR both needs a review AND has a one-line body), ask ONE clarifying question before routing. Heuristics that help disambiguate:

• Repo already has .github/workflows/pr-review.yml (or similar) →

probably NOT the setup flow.

• Repo has no .github/workflows/pr-review.yml (or similarly-named

AI Diff Reviewer workflow — grep the .github/workflows/ tree for DailybotHQ/ai-diff-reviewer or ai-diff-reviewer action refs) AND no .review/extension.md, and the developer just installed the skill → ask which of the two flows they want ("Flow A local-only" vs "Flow B dual-surface"; see the "Two supported flows" section above). Do NOT default to setup — Flow A (local-only) is a first-class use case, and running setup unrequested would write .github/workflows/pr-review.yml and force the CI Action into a repo where the developer may not want it. The presence of unrelated workflows (CI tests, deploy pipelines, dependency bots) is NOT evidence of Flow B; only an ai-diff-reviewer workflow is.

• Developer just finished a session of code changes and hasn't asked for

a review yet → default review flow (local).

• The word "review" is ambiguous when a PR already exists for the

current branch AND has live <!-- ai-pr-reviewer-marker --> comments from a recent CI run. In that case, "read the review" usually means the CI review on the PR (apply-review flow), not a fresh local one. Ask once: "Read the CI review that just landed on PR #N, or run a new local review on your working tree?"

• Developer just accepted a local review's findings and applied fixes

→ probably the open-pr flow (natural next step, first PR of the session).

• Developer just applied fixes from the CI review → probably open-pr

in edit mode (to refresh the PR body if the scope changed), then git commit + git push (they'll do it themselves).

Some harnesses (Claude Code, Cursor) also expose these as slash commands (/ai-diff-reviewer, /ai-diff-reviewer-generate-extension, /ai-diff-reviewer-setup, /ai-diff-reviewer-open-pr, /ai-diff-reviewer-apply-review); check the harness's skill-invocation docs.

Default flow: how the local review works

Everything below (Steps 0 through 5) describes only capability #1 from the table above — running the review on the current branch. The four sibling sub-skills have their own procedures in their respective SKILL.md files:

• `generate-extension/SKILL.md` — author .review/extension.md
• `setup/SKILL.md` — install the GitHub Action
• `open-pr/SKILL.md` — author the PR title + body
• `apply-review/SKILL.md` — read + apply the CI review posted on the PR

Step 0 — Trust boundary

This skill is near read-only on the working tree and does not call any remote API. It:

• Reads files from the current git checkout (Read, Grep, Glob).
• Runs git diff and git log locally (no push, no fetch).
• Composes the review prompt in the agent's context and produces the

review as terminal output.

The only writes it may perform, and only with explicit developer consent in Step 2.5:

• Create .review/ and write .review/extension.md — if the developer

answers yes to the bootstrap offer (invokes the generate-extension sub-skill).

• Create .review/ and touch .review/.skip-bootstrap (0 bytes) — if

the developer answers never to the bootstrap offer.

It does not:

• Post inline comments to GitHub (that's the CI action's job).
• Modify any source file, workflow, or config file in the working tree.
• Call the LLM provider directly — it uses the coding agent that's

already running you.

• Send any data off your machine.

If the coding agent has broader powers (e.g. can write files or run arbitrary bash), those come from the harness, not this skill.

Step 1 — Detect context

Run these to establish the review's inputs. Emit the JSON to your working context; do not print it to the user unless they ask.

# Base branch: prefer the tracked upstream's short name, fall back to `main`.
BASE=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null | sed 's|.*/||')
BASE="${BASE:-main}"

# Current branch + head SHA
HEAD_BRANCH=$(git branch --show-current)
HEAD_SHA=$(git rev-parse --short HEAD)

# The three artifacts the review needs
git diff --stat "origin/${BASE}...HEAD"    # summary of what changed
git diff "origin/${BASE}...HEAD"           # the actual diff
git log "origin/${BASE}..HEAD" --oneline   # the commit trail

If the diff is empty, tell the developer "no changes vs <BASE> — nothing to review" and stop. If origin/${BASE} doesn't exist (fresh clone, missing remote), fall back to git merge-base main HEAD and diff against that; note the fallback in the summary.

Step 2 — Compose the prompt (base + extension)

The review methodology lives in `prompt.md` — the exact same prompt the CI action ships. Read it into your context as the base.

Then check for a repo-specific extension in this order of precedence (first match wins; the rest are ignored):

1. .review/extension.md (recommended convention — runtime-agnostic)
2. .github/ai-diff-reviewer/extension.md (fallback for teams that

prefer .github/ sibling to workflow files; .github/ai-pr-reviewer/extension.md also accepted for back-compat with the pre-v1.5 skill name)

If a match is found — read it, append its content to the base prompt verbatim, and skip to Step 3.

If no match is found:

• If .review/.skip-bootstrap exists → the developer opted out of the

bootstrap offer previously. Use the base prompt alone (no announcement), skip to Step 3.

• Otherwise → go to Step 2.5 (first-time bootstrap offer).

Announce the composed configuration in one line, e.g. Reviewing feat/foo (a1b2c3d) against main. Base prompt + .review/extension.md.

The final composed prompt is what governs the review — the severity definitions, the "what NOT to comment on" rules, the output shape.

Step 2.5 — Offer to bootstrap the extension (first-time only)

This step fires only when Step 2 found no extension file and no .review/.skip-bootstrap marker exists. It's the one moment the skill educates the developer about the extension convention. After the answer is recorded (either as generated content or an opt-out marker), the skill never asks again in this repo unless the developer removes the marker.

Ask the developer ONE question:

No `.review/extension.md` found for this repo. I can run the review right now with the shipped default prompt — that catches ~90% of general-purpose issues (SQL injection, unhandled promises, missing input validation, obvious perf regressions, etc.). But it will miss the repo-specific stuff: your money-handling conventions, the modules where console.log is banned, the RFC-014 pattern, the always-critical SQL patterns tied to YOUR schema. That's what a .review/extension.md gives you — file-anchored severity overrides written against THIS codebase. Want to bootstrap one now? (~30 seconds of Discovery + a ~100-line file of concrete overrides.) - yes — I'll route to the generate-extension sub-skill, then come back and run the review with the fresh extension layered on. - no — run the review this once with the base prompt only. I'll ask again the next time the skill activates. - never — never ask again in this repo. I'll create .review/.skip-bootstrap (a tracked 0-byte marker). Commit it so your whole team inherits the same preference. To re-enable the offer later, delete the marker.

Handle the response:

• yes → invoke the generate-extension sub-skill in extension mode

(see `generate-extension/SKILL.md`). When the sub-skill finishes writing .review/extension.md, re-enter Step 2 from the top — the freshly-written file will be picked up and layered onto the base prompt. Do NOT skip the sub-skill's Discovery phase (12+ tool calls); that's where the value is.

• no → skip to Step 3 with the base prompt alone. Do NOT persist

anything. The offer fires again next time.

• never → run:

  mkdir -p .review
  touch .review/.skip-bootstrap

Then skip to Step 3 with the base prompt alone. Suggest the developer commit the marker: git add .review/.skip-bootstrap && git commit -m "chore(review): opt out of AI Diff Reviewer bootstrap offer".

If the developer's response is ambiguous, default to no (the minimally-disruptive choice) — do not silently opt them out.

Step 3 — Execute the review

Apply the composed prompt to the diff using the coding agent's own tools (Read, Grep, Glob):

• The prompt tells you to read_file / grep / glob — translate those

to whatever primitives the harness gives you. Read the changed files in full; the diff alone is rarely enough context.

• The prompt tells you to post_inline_comment(path, line, body, severity)

— since you are running locally without GitHub write access, instead collect each finding into an internal list of {path, line, severity, body} records and print them as a table in Step 4.

• The prompt tells you to submit_review(summary) exactly once — this

is your cue that the review is complete. When you reach this point, print the final summary and stop.

Cost discipline: cap yourself at the same number of turns the CI action does (~25) and the same inline-comment cap (default 20). Don't grep the whole world; grep the files you're commenting on plus their imports.

Step 4 — Print the review

Emit the review to the terminal in the same format the CI bot would post on a PR — this is the parity contract:

## Verdict
<one sentence — "Looks good", "Blocking security fix needed", etc.>

## Findings

| # | Severity | File | Summary |
|---|----------|------|---------|
| 1 | 🚨 critical | `src/auth.ts:55` | SQL injection in raw-string login query |
| 2 | ⚠️ warning  | `src/cache.ts:120` | Unbounded cache key cardinality |
| 3 | ℹ️ info     | `tests/utils.ts:12` | Helper could be reused from existing fixture |

### 1. `src/auth.ts:55` — 🚨 critical
<the full finding body — 2-4 sentences + optional ```suggestion block```>

### 2. `src/cache.ts:120` — ⚠️ warning
<...>

### 3. `tests/utils.ts:12` — ℹ️ info
<...>

## Notes (no inline anchor)
- <cross-cutting concerns, architecture, test-strategy comments>

**Recommendation:** approve / request-changes / comment-only

A recommendation is not a check result. On CI, the GitHub check is decided by the runtime's strictness gate, which can still be failing while the model recommends approve — under incremental review, prior findings the model believes are fixed may still be outstanding. CI reviews from v2.3.1+ therefore end with a runtime-written > **Check status: …** block, and the tracking comment's **Strictness gate:** line is always authoritative. Never report that a review "passed" from the recommendation line alone; apply-review Step 2f covers how to read the real outcome.

Reproducing this exact shape (verdict → findings table → per-finding body → notes → recommendation) is what lets a developer trust the same methodology and severity model on both surfaces. On CI round 2+ of a generation, Iteration-Aware Review may additionally dedupe findings that a local full pass would still list — that difference is expected, not a parity bug (see CI-only surfaces above).

Optional next-step hint. When the review is clean (no 🚨 critical or ⚠️ warning findings) OR when the developer explicitly signals they're ready to push, close the output with a one-line pointer to the sibling sub-skill:

Next step: want me to open the PR? — I can draft the title + body from
this same diff (see the `open-pr` sub-skill). Or run `gh pr create`
yourself.

Do not print this hint when the review found blocking issues — fix first, ship second.

Step 5 — Extension file convention (for consumers)

Three ways to end up with an extension file, all valid:

1. Automated bootstrap — say "review my branch" on a fresh repo,

answer yes at the Step 2.5 prompt. The generate-extension sub-skill runs its 12+ tool-call Discovery and writes .review/extension.md for you. Simplest path — recommended for the first setup.

1. Explicit sub-skill invocation — say "generate a

.review/extension.md for this repo" (or one of the other triggers listed in Activation). Same result as (1) but skips the bootstrap prompt. Use this to regenerate or refine an existing file.

1. Hand-written — create the file yourself, using the schema and

examples below. Best when you know exactly what overrides you want and don't need the Discovery walkthrough.

Whichever path you take, the layout options are the same:

Option A — `.review/extension.md` (recommended):

my-repo/
├── .review/
│   └── extension.md         ← auto-detected by this skill
└── .github/
    └── workflows/
        └── pr-review.yml    ← CI workflow uses the same file

Option B — `.github/ai-diff-reviewer/extension.md` (fallback if you prefer keeping the file next to your workflows). The pre-v1.5 path .github/ai-pr-reviewer/extension.md is still recognised for back-compat.

The same file should be referenced from your CI workflow's prompt-extension-file: input so local and CI stay in perfect sync:

# .github/workflows/pr-review.yml
- uses: DailybotHQ/ai-diff-reviewer@v2
  with:
    api-key: ${{ secrets.ANTHROPIC_API_KEY }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    prompt-extension-file: .review/extension.md   # same file the skill auto-detects

Example .review/extension.md:

## Severity overrides for our codebase

- Any `SELECT * FROM users` in a request path is **critical** (PII exposure).
- Missing `AbortController` on a `fetch()` in `apps/frontend/` is **warning**
  (React 18 pattern we standardized on in RFC-014).

## Don't comment on

- Formatting in `apps/legacy/*` — that module is scheduled for a rewrite.
- Missing tests in `experiments/` — that folder is intentionally exploratory.

Full authoring guide (structure, tips, worked examples): `docs/PROMPTS.md`.

Notes

• **The skill runs your local agent — it doesn't invoke a separate

LLM.** If your harness is Cursor and you're on auto, the review costs are billed to your Cursor Pro subscription. If your harness is Claude Code with an API key, it's Anthropic tokens. Either way the local review is a "free bonus" if you were going to use the agent anyway.

• **When paired with the CI Action (Flow B), this skill does not

replace it.** The CI Action still runs on every PR and posts the authoritative review (inline comments, severity gating, merge-blocking); the skill is for the "before pushing" moment. In Flow A (local-only), the local skill IS the entire reviewer — no CI leg, no post-push authority; findings live only in your terminal and you decide what to act on before opening the PR.

• **Extension parity is guaranteed on your side, not enforced by

tooling.** If your .review/extension.md says something different from what your CI workflow's prompt-extension-file: points at, you get drift. Keep them at the same path.

• Opt-out marker (`.review/.skip-bootstrap`). A 0-byte tracked

marker file that tells the skill "don't offer to bootstrap the extension anymore in this repo — the team knows the option exists and chose to stick with the base prompt." Created by answering never at the Step 2.5 prompt. Delete the file to re-enable the offer. Committing it is the intended behaviour so the whole team inherits the same UX.

• **Bugs, feature requests, and extension patterns to add to the

starter templates:** `github.com/DailybotHQ/ai-diff-reviewer/issues`.