/adversarial-pr-review

name: adversarial-pr-review
description: Adversarial spec-compliance PR review — cross-references diffs against approved specs, verifies runtime claims against source, detects competing PRs, audits scope/convention compliance. Use before merging.
version: 1.0.0
user-invocable: true
format: 2025-10-02
status: ACTIVE
updated: 2026-04-15
triggers:
  - reviewing a pull request before merge
  - cross-referencing a diff against an approved spec
  - auditing PR scope/convention compliance or detecting competing PRs

Adversarial PR Review

> Adversarial review with spec-compliance focus. Reviews PRs like a hostile-but-fair reviewer — verifies that what the PR *claims* matches what it *actually does* and what the *approved spec requires*.

REVIEW SCOPE

Accept one of:

• `--pr <N>` — review a single PR
• `--all` — review all open PRs by the current author
• `--branch <name>` — review the diff on a specific branch against main
• (no args) — review the current branch's diff against main

PHASE 1: CONTEXT GATHERING

For each PR under review, collect:

1.1 PR metadata

gh pr view <N> -R Tibsfox/gsd-skill-creator --json title,body,headRefName,labels,reviewDecision,statusCheckRollup,files

1.2 Linked issue and approval status

Extract issue number from PR body (`Closes #N`, `Fixes #N`, `Resolves #N`).

gh api repos/Tibsfox/gsd-skill-creator/issues/<N> --jq '{title, labels: [.labels[].name], state, body}'

Verify:

• Issue exists and is open (or was open when PR was created)
• Extract **acceptance criteria** from the issue body — these are the spec
• If no linked issue, note as **INFO** — not all PRs need issues

1.3 Approved scope

From the issue body or PR description, extract:

• **Files listed as in-scope for modification**
• **Acceptance criteria / success criteria**
• **Explicit constraints** ("must", "must not", "required")
• **Field names, flag names, CLI commands** mentioned in the spec

1.4 Competing PRs

gh pr list -R Tibsfox/gsd-skill-creator --state open --search "closes #<issue_number> OR fixes #<issue_number>" --json number,author,title

If multiple PRs target the same issue, flag the competition.

1.5 Full diff

gh pr diff <N> -R Tibsfox/gsd-skill-creator

Or for branch mode:

git diff main...HEAD

PHASE 2: SPEC-COMPLIANCE AUDIT

Cross-reference every claim against reality.

2.1 Scope compliance

Compare files in the diff against files listed in the approved issue scope:

| Check | Verdict | |-------|---------| | All in-scope files are modified | PASS / **UNDER-DELIVERY** | | Only in-scope files are modified | PASS / **SCOPE CREEP** | | Modifications match approved intent | PASS / **DEVIATION** |

2.2 Acceptance criteria verification

For each acceptance criterion in the approved issue:

1. **Is it implemented?** Search the diff for evidence 2. **Is it implemented correctly?** Cross-reference field names, flag names, behavior descriptions against the spec 3. **Is it tested?** Check test files for assertions that would catch regressions 4. **Does the test actually verify the criterion?** Tautological tests don't count

Flag any criterion that is:

• Missing entirely (not implemented)
• Partially implemented (behavior differs from spec)
• Implemented but untested
• "Tested" but the test is tautological

2.3 Schema and interface verification

When the spec defines a data schema, API interface, or config shape:

1. Extract field names from the spec 2. Extract field names from the implementation 3. Compare — flag any divergence 4. If fields are marked required in the spec, verify they are required in the implementation

2.4 Import boundary verification

This repo has strict import boundaries (CLAUDE.md):

• `src/` never imports `desktop/@tauri-apps/api`
• `desktop/` never imports Node.js modules
• Flag any cross-boundary imports in the diff

PHASE 3: RUNTIME CLAIM VERIFICATION

Verify that runtime references in the code actually exist.

3.1 Import and dependency verification

When the diff adds new imports:

# Check the import target exists
grep -r "export.*<name>" src/ desktop/

If the imported symbol doesn't exist, this is **BLOCKING**.

3.2 Skill and agent references

When code references skills (`.claude/skills/`) or agents (`.claude/agents/`):

• Verify the referenced skill/agent directory exists
• Verify the SKILL.md or agent definition file is present
• Check that `subagent_type` values in Agent calls match defined agent types

3.3 Config and settings verification

When code references settings or config fields:

grep -n "<field_name>" .claude/settings.json src/

Verify field names, defaults, and types match the source of truth.

3.4 Command and workflow references

When workflows reference GSD commands (`.claude/commands/gsd/`):

• Verify the command file exists
• Verify frontmatter matches actual behavior

PHASE 4: CONVENTION COMPLIANCE

Check project conventions per CLAUDE.md.

4.1 Commit convention

• Conventional Commits: `<type>(<scope>): <subject>`
• Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
• Imperative mood, lowercase, no period, subject <72 chars

4.2 Test conventions

For test files:

• Uses Vitest (not Jest/Mocha/Chai) — `import { describe, it, expect } from 'vitest'`
• Tests verify meaningful behavior, not just existence
• No tautological assertions

4.3 TypeScript conventions

• Strict mode compliance
• No `any` types without justification
• Proper error handling at system boundaries

4.4 Skill conventions

For skill files in `.claude/skills/`:

• Frontmatter: `name`, `description` required
• Description within the 1-1024 char bound (docs/OFFICIAL-FORMAT.md:64); flag as a soft nit only if it lacks a "Use when..." trigger clause, not on raw length
• `version` present for versioned skills
• `user-invocable: true` only if the skill should be directly callable

4.5 Documentation

• Release notes follow ch