pre-pr-scan

name	pre-pr-scan
description	Pre-PR compliance and security scan. Checks diff against CLAUDE.md guidelines and security best practices before creating a pull request.
license	MIT
metadata	{"author":"jonathanprozzi","version":"1.0.0"}
context	fork
agent	general-purpose
disable-model-invocation	true
argument-hint	[base-branch] [--validate] [--all] [--quick] [--run-checks] [--output <path>] [--guidelines <paths...>]
allowed-tools	Read, Grep, Glob, Bash(git *), Task, Write

Pre-PR Scan

You are performing a pre-PR compliance and security scan. Your goal is to catch issues BEFORE a pull request is created, mimicking what the Claude PR review bot would flag.

IMPORTANT: Static analysis by default. Do NOT run tests, linters, or build commands unless --run-checks flag is provided. Running tests is the user's responsibility. Your job is to analyze code and diffs to identify potential issues - not to execute anything.

If --run-checks is provided, run the project's lint, test, and build commands (matching what CI would run) and include results in the report.

Dynamic Context

Changed Files

!git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~5

Diff Stats

!git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~5

Note on context: The agent will fetch the full diff and locate CLAUDE.md files during execution. If the diff is large (>1000 lines), parallel mode will be used automatically.

To find project guidelines, look for CLAUDE.md in the repo root and subdirectories. Read any found guidelines before scanning.

Note: If --guidelines <paths...> is provided, read those files instead of auto-discovering. Example:

/pre-pr-scan --guidelines ./CLAUDE.md ./packages/api/CLAUDE.md

This is useful for monorepos where each package has its own guidelines.

---

Flags

Parse the arguments passed to this skill. Set these variables based on what's present:

Flag	Variable	Effect
--validate	VALIDATE_HIGH=true	Run validation pass on HIGH issues
--all	SHOW_ALL=true	Include issues below 80% confidence
--quick	QUICK_MODE=true	Use Haiku for all agents (fastest)
--run-checks	RUN_CHECKS=true	Run lint/test/build commands (like CI)
--output <path>	OUTPUT_PATH	Write report to file (in addition to stdout)
--guidelines <paths...>	GUIDELINES_PATHS	Explicit CLAUDE.md file paths

Default behavior (no flags): Static analysis only, ≥80% confidence threshold, no validation pass, auto-discover CLAUDE.md.

Flag combinations:

• --validate alone: Full scan + validation (~300k tokens, 80% precision on HIGH)
• --quick alone: Fast scan, Haiku everywhere (~80-100k tokens)
• --all alone: See speculative issues for awareness
• --quick --validate: Not recommended (defeats purpose of quick)
• --output ./scan-results.md: Save report to file for later reference
• --guidelines ./CLAUDE.md ./packages/core/CLAUDE.md: Explicit guideline files (monorepos)

---

No CLAUDE.md?

If no CLAUDE.md is found in the project, the skill automatically falls back to:

• Bug detection (logic errors, missing error handling, race conditions)
• Security scanning (OWASP + Web3 + AI/LLM)
• TypeScript/code quality checks

This makes the skill portable to any repo, even without project-specific guidelines.

---

Mode Selection

Based on the Diff Stats above (look at the summary line showing files changed and insertions/deletions), select the appropriate mode:

Small PR Mode (< 1000 total changes AND < 15 files)

Run the scan sequentially as a single agent. Skip to Sequential Scan Process below.

Large PR Mode (≥ 1000 total changes OR ≥ 15 files)

Spawn 4 parallel agents with partitioned responsibilities (no overlap). Follow Parallel Scan Process below.

Token efficiency: Each agent analyzes the diff first, only reading max 5 full files. This prevents duplicate file reads across agents.

To get the full diff for analysis, run: git diff main...HEAD (or git diff HEAD~5 if no main branch).

---

Parallel Scan Process

For large PRs, use the Task tool to spawn 4 parallel agents. Each agent has a distinct responsibility with no overlap to minimize token usage.

Token Efficiency Rules

1. Analyze diff FIRST - Look for issues in the diff before reading full files
2. Max 5 deep-dives per agent - Only read full files when diff shows a potential issue
3. No responsibility overlap - Each agent owns specific issue types exclusively

Agent Prompts

Agent 1: CI Failures + CLAUDE.md Compliance

You detect issues that will BREAK CI (compilation, tests) and CLAUDE.md violations.

STEP 1: Get the diff
git diff main...HEAD

STEP 2: Scan diff for CI-breaking patterns (DO NOT read files yet)
- Duplicate imports/exports (same name imported twice)
- Duplicate function definitions
- Missing imports (used but not imported)
- Type errors visible in diff (wrong types passed)

STEP 2.5: Check for duplicate definitions in codebase
- Extract function/const/class names ADDED in diff (lines starting with +)
- For each name, grep codebase: git grep -n "function <name>\|const <name>\|class <name>" -- '*.ts' '*.tsx'
- Flag: If name exists elsewhere AND is being added (not moved), it's a duplicate
- This catches compilation errors the diff alone won't show

STEP 3: Check test coherence
- Get test files: git diff --name-only main...HEAD | grep -E '\.(test|spec)\.(ts|tsx)$'
- For each test file, identify its subject (e.g., foo.test.ts tests foo.ts)
- Compare test assertions to actual implementation
- Flag: tests expecting states/functions that don't exist

STEP 4: Read CLAUDE.md, scan diff for violations
- Only read CLAUDE.md once
- Check diff against guidelines (don't read implementation files)

STEP 5: Deep-dive (MAX 5 FILES)
- Only read full files if diff shows a likely issue
- Confirm or reject the issue with full context

EXCLUSIVE FOCUS: CI failures (compilation, test mismatches) + CLAUDE.md
DO NOT CHECK: Security, null access, error handling (other agents handle these)

Output format:
### [HIGH|MEDIUM|LOW]: [Title]
**Confidence:** [80-100]%
**File:** `path:line`
**Category:** [CI Failure | CLAUDE.md Compliance | Test Coherence]
**Issue:** [description]
**Impact:** [CI will fail because...]
**Fix:** [recommendation]

Agent 2: Security Vulnerabilities

You detect SECURITY issues only. No type checking, no error handling.

STEP 1: Get the diff
git diff main...HEAD

STEP 2: Grep diff for security patterns (DO NOT read files yet)
- Hardcoded secrets: API keys, tokens, passwords in strings
- Injection: User input in SQL/commands/HTML without sanitization
- Web3: Addresses without checksum validation, private key handling
- Auth: Missing authorization checks, IDOR patterns

STEP 3: Deep-dive (MAX 5 FILES)
- Only read files where diff shows a security-relevant pattern
- Confirm the vulnerability with full context

EXCLUSIVE FOCUS: Security vulnerabilities (OWASP + Web3)
DO NOT CHECK: Type errors, null access, error handling, CLAUDE.md (other agents)

Output format:
### [HIGH|MEDIUM|LOW]: [Title]
**Confidence:** [80-100]%
**File:** `path:line`
**Category:** Security
**Vulnerability:** [OWASP category or Web3 issue type]
**Issue:** [description]
**Impact:** [what an attacker could do]
**Fix:** [recommendation]

Agent 3: Logic Bugs + Error Handling

You detect RUNTIME BUGS. No security, no type checking.

STEP 1: Get the diff
git diff main...HEAD

STEP 2: Scan diff for bug patterns (DO NOT read files yet)
- Null/undefined access: obj.property without null check
- Array bounds: arr[index] without length check
- Race conditions: async operations without proper ordering
- Missing error handling: .then() without .catch(), no try/catch
- Resource leaks: opened but never closed

STEP 3: Deep-dive (MAX 5 FILES)
- Only read files where diff shows a likely bug
- Check surrounding context to confirm

EXCLUSIVE FOCUS: Runtime bugs, error handling, logic errors
DO NOT CHECK: Security, type mismatches, CLAUDE.md (other agents)

Output format:
### [HIGH|MEDIUM|LOW]: [Title]
**Confidence:** [80-100]%
**File:** `path:line`
**Category:** Bug Detection
**Issue:** [description]
**Impact:** [what will crash/fail at runtime]
**Fix:** [recommendation]

Agent 4: History Analyzer (use Haiku - no file reads needed)

You analyze COMMIT PATTERNS only. No file reading.

STEP 1: Get commit history
git log --oneline main...HEAD

STEP 2: For each commit, check the stat
git show <hash> --stat

STEP 3: Look for patterns
- Flip-flopping: Code added then removed across commits
- Incomplete: Feature without tests, API without client update
- Contradictions: Commits that undo earlier work
- Large commits: Should be split for reviewability
- Vague messages: "fix", "update", "changes" without context

NO FILE READS - History analysis only.

Output format:
### [HIGH|MEDIUM|LOW]: [Title]
**Confidence:** [80-100]%
**Commits:** `abc123`, `def456`
**Category:** History Analysis
**Issue:** [description]
**Pattern:** [what the history shows]
**Fix:** [recommendation]

Spawning Agents

Use the Task tool with these parameters for each agent:

• subagent_type: "general-purpose" (Agents 1-3) or "Explore" (Agent 4)
• description: "[Agent name]"
• prompt: [The prompt above]
• model: See model selection below

Why general-purpose for Agents 1-3? These agents need to read files for deep-dives. The Explore subagent type has restricted permissions when running in parallel/background, causing tool access to be denied. general-purpose agents have full tool access.

Agent 4 uses Explore because it only runs git commands (no file reads needed).

Model selection:

• Default: Haiku for Agent 4 only, Sonnet for Agents 1-3
• --quick mode: Haiku for ALL agents (fastest, ~50% token savings)

IMPORTANT: Spawn all 4 agents in a SINGLE message to run them in parallel.

Aggregating Results

After all agents complete:

1. Collect all issues from all 4 agents
2. Deduplicate (same file + same issue = keep one)
3. Sort by severity (HIGH → MEDIUM → LOW), then by confidence (highest first)
4. If --validate flag: Run validation pass on HIGH issues (see below)
5. If --all flag: Include issues below 80% confidence (mark as "SPECULATIVE")
6. Output in the standard format below

Validating HIGH Issues

Skip this section unless --validate flag is set.

For each HIGH severity issue, spawn a validation agent to confirm:

You are validating a potential HIGH severity issue.

ISSUE: [description from original agent]
FILE: [file path]
CLAIMED PROBLEM: [what the agent said is wrong]

Your job:
1. Read the file and surrounding context
2. Determine if this is a REAL issue or false positive
3. Return: CONFIRMED or REJECTED with brief explanation

Be strict - only CONFIRM if you are certain the issue exists.
If the code might be intentional or context-dependent, REJECT.

Use the Task tool with:

• subagent_type: "general-purpose" (needs file read access)
• model: "sonnet" (for thorough validation)
• description: "Validate: [issue title]"

Spawn validators in parallel for all HIGH issues, then filter to only CONFIRMED issues.

This multi-pass validation reduces false positives on critical issues.

---

Sequential Scan Process

For small PRs, perform all checks yourself. Work from the diff (provided above) first.

Phase 1: CI Failure Detection (HIGHEST PRIORITY)

Check for issues that will break the build:

1. Duplicate definitions: Same import/function/variable defined twice
2. Duplicate definitions in codebase:
   • Extract function/const/class names ADDED in diff
   • Grep codebase to check if name already exists elsewhere
   • Flag if adding a name that already exists (compilation will fail)
3. Missing imports: Used but not imported
4. Type errors in diff: Wrong types visible in the changed code
5. Test coherence: Test files expecting states/functions that don't exist
   • For each *.test.ts or *.spec.ts in changed files, verify assertions match implementation

Phase 2: CLAUDE.md Compliance Audit

If CLAUDE.md exists, audit changes against its guidelines:

1. Read CLAUDE.md once - understand the guidelines
2. Scan diff for violations - check patterns in the diff itself
3. Deep-dive only if needed - read full files only to confirm issues
4. Cite the specific guideline being violated

Phase 3: Security Scan (OWASP + Web3 + AI)

Scan the diff for security patterns:

Traditional Security (OWASP Top 10)

• Injection: SQL, NoSQL, command injection patterns
• Sensitive Data: Hardcoded secrets, API keys in strings
• XSS: Unsanitized user input rendered in output

Web3/Blockchain Security (if applicable)

• Address Validation: Unchecksummed addresses (use getAddress())
• Transaction Safety: Missing gas checks, unvalidated params

AI/LLM Security (if applicable)

• Prompt Injection: User input directly in prompts
• PII Leakage: Sensitive data in prompts or logs

Phase 4: Logic Bugs + Error Handling

Scan the diff for runtime bug patterns:

• Null/undefined access: obj.property without null check
• Array bounds: arr[index] without length check
• Missing error handling: .then() without .catch()
• Race conditions: Async operations without proper ordering

Phase 5: History Analysis

Analyze commit history for patterns:

• Flip-flopping: Code added then removed across commits
• Incomplete changes: Features without tests
• Contradictions: Commits that undo earlier work
• Commit hygiene: Large commits that should be split

---

Confidence Scoring

Every issue MUST include a confidence score:

Range	Meaning	Reported?
95-100%	Definite issue, clear violation	Always
90-94%	Very likely, strong evidence	Always
85-89%	Probable, good evidence	Always
80-84%	Possible, meets threshold	Always
60-79%	Speculative, needs investigation	Only with --all
<60%	Low confidence, likely noise	Never

Default: Only ≥80% issues reported. With --all: 60-79% issues included, marked as "SPECULATIVE" in output.

---

Output Format

## Pre-PR Scan: [branch] vs main

**Mode:** [Sequential | Parallel (4 agents)]
**Flags:** [--validate, --all, --quick, or "none"]
**Files scanned:** X changed files
**Commits analyzed:** Y commits
**Issues found:** Z (A High, B Medium, C Low)
**Validated:** [If --validate: "X/Y HIGH confirmed" | else: "skipped"]

---

### HIGH: [Issue Title]
**Confidence:** [80-100]%
**File:** `path/to/file.ts:42` (or **Commits:** for history issues)
**Category:** [CLAUDE.md Compliance | Security | Bug | TypeScript | History]
**Guideline:** [If CLAUDE.md issue, cite specific lines]
**Issue:** [What's wrong]
**Impact:** [Why it matters]
**Fix:** [How to fix]

---

### MEDIUM: [Issue Title]
...

---

## Summary

[Brief summary of findings and recommended actions before creating PR]

---

Rules

1. Only scan changed files - Don't flag pre-existing issues
2. Cite guidelines explicitly - For CLAUDE.md issues, quote the rule
3. Be specific - Include file path and line number
4. Filter noise - Don't report:
   • Issues linters would catch (ESLint, TypeScript compiler)
   • Style preferences not in CLAUDE.md
   • Hypothetical issues without concrete evidence
5. Prioritize by impact - HIGH = security/data loss, MEDIUM = bugs/maintainability, LOW = improvements
6. Actionable fixes - Every issue must have a clear fix recommendation

Confidence Threshold

Default (no --all): Only report issues ≥80% confidence. Skip:

• Speculative issues (60-79%)
• Context-dependent patterns that might be intentional
• Issues that require more context to verify

With --all: Include 60-79% issues, but mark them clearly:

### SPECULATIVE: [Issue Title]
**Confidence:** 72%
**Note:** Below threshold - included due to --all flag

---

Begin Scan

1. Check the Diff Stats to determine mode (Sequential vs Parallel)
2. If Parallel: spawn 4 agents using Task tool, aggregate results
3. If Sequential: run all 4 phases yourself
4. Output findings in the format above, sorted by severity then confidence
5. If --output <path> flag: Write the complete report to the specified file using the Write tool

Output to File

If OUTPUT_PATH is set:

• Write the complete markdown report to the specified path
• Use the Write tool (not Bash)
• Include all sections: header, issues, summary
• The report is written in addition to stdout output (user sees both)