All skills

Bug Hunting & Review

Apex Bug Hunter

Execute deep multi-pass bug hunting, differential pull request reviews, branch comparisons, full-repository architectural audits, tight-loop bug diagnosis, performance regression bisection, and zero-regression fixes. Trigger automatically whenever the user asks to hunt bugs, review a pull request (PR #N), audit a branch against main, audit the entire main branch or codebase, diagnose production regressions or flaky tests, verify an engineering report, audit MCP or OAuth protocol compliance, or fix severe defects.

What this skill adds

A deterministic, multi-stage bug-hunting, differential code review, tight-loop root-cause diagnosis, and zero-regression remediation skill. It unifies the CodeRabbit 4-Stage AST and Call-Graph Review Pipeline, Obra Superpowers Systematic Debugging (`systematic-debugging`, `root-cause-tracing`, `defense-in-depth`, `condition-based-waiting`, `verification-before-completion`), Matt Pocock's Engineering Discipline (`diagnosing-bugs` hard phase gates, `code-review` orthogonal axis separation, `tdd` seam and anti-pattern rules, `improve-codebase-architecture` deep-module deletion test, and `retro` environment hardening), Andrej Karpathy's 4 Surgical Coding Laws, and Ponytail Zero-Regression Engineering.

When to Use

  • Auditing a Pull Request (PR #N), commit range, or uncommitted working-tree diff for bugs, contract drift, or security flaws
  • Comparing a feature or fix branch against main or origin/main
  • Performing a whole-branch or full-repository architectural, boundary, contract, concurrency, and state-machine audit
  • Diagnosing a specific hard bug, flaky test, or performance regression using a tight reproduction loop and git bisect
  • Auditing an AI agent's engineering report or "green build" claim against actual HEAD source code and runtime behavior
  • Executing surgical, zero-regression fixes with cold verification and granular GPG-signed commits

1. Cognitive Locks: Anti-Sycophancy, Anti-Short-Circuiting, and Anti-Hallucination

  • Before inspecting files or emitting any analysis, engage all four cognitive locks. These locks apply with maximum strictness to fast or lightweight models (including Gemini Flash). For full enforcement criteria, read references/anti-reward-hacking-and-verification-locks.md.
  • ### 1.1 Strict Prohibition of AI Sycophancy
  • Ban all performative agreement, flattery, conversational filler, and premature celebratory claims (such as "Great question!", "Your code is well-structured!", or "Fixed flawlessly!").
  • State findings, root causes, and verification outputs plainly with exact file:line evidence.
  • ### 1.2 Strict Prohibition of AI Short-Circuiting (Flash-Model Lock)
  • Never skim file headers, guess function behavior from identifiers, or skip passes after finding an early bug.

2. Universal Scope Resolution, Complexity Router, and Two-Stage Gate

  • Resolve the operational scope from the user's request before starting Pass 1. Run scripts/preflight-diff-and-boundary-scan.sh (or node scripts/preflight-diff-and-boundary-scan.js) and node scripts/verify-mcp-and-schema-parity.js to gather deterministic baseline telemetry.
  • ### 2.1 Four-Lane Operational Scope & Complexity Router
  • | Mode | Trigger Condition | Inspection Scope |
  • | :--- | :--- | :--- |
  • | **Pull Request Mode** | User specifies PR #N or a PR URL | Audit git diff <base>...<head>, all PR commits, full PR/issue comment threads, and all upstream callers and downstream callees in the AST symbol graph |
  • | **Branch & WIP Diff Mode** | User specifies a branch name or local diff | Audit git diff origin/main...<branch> PLUS uncommitted staged and working-tree changes (git diff HEAD and git status --porcelain) plus transitive call-graph dependencies |

3. The 8-Pass Inspection Pipeline

  • Execute all eight passes in sequence. Do not skip passes even if an early pass discovers a blocker:
  • **Pass 1: Governance, Invariants, and External Specification Grounding:** Read AGENTS.md, CLAUDE.md, CODING_STANDARDS.md, GLOSSARY.md, INVARIANTS.md, HALL_OF_SHAME.md, .out-of-scope/, and official protocol specifications (MCP 2025-06-18/2025-11-25, OAuth 2.1, RFC 8707).
  • **Pass 2: Differential Line-Deletion (-), Working-Tree, and Boundary Validation Audit:** Inspect deleted lines against DEL-01..08, apply Ousterhout's Deep-Module Deletion Test, and trace AST symbol blast radius.
  • **Pass 3: Contract, Protocol, and Output Schema Parity Audit:** Verify 100% return-branch structuredContent parity across all tools declaring outputSchema, enforce array-level truncation, verify isError: true, deep-clone via structuredClone, and enforce zero UTF-8 BOM.
  • **Pass 4: State Machine, Hierarchy, Collision, and Idempotency Audit:** Verify pure reads, parent existence, trash-batch hints, cycle detection (A -> B -> A), sibling name collision (CONFLICT), multi-match disambiguation (AMBIGUOUS), active-first resolution, wired pagination cursors, and atomic clientRequestId locking.
  • **Pass 5: Concurrency, Async Race Conditions, and condition-based-waiting Audit:** Detect TOCTOU races, enforce atomic database operations (SELECT ... FOR UPDATE or INSERT ... ON CONFLICT), and replace arbitrary sleeps (setTimeout, waitForTimeout) with explicit state condition predicates.

Default agent prompt

Use $apex-bug-hunter to audit this pull request against main, detect latent bugs, verify external protocol schemas, and engineer surgical zero-regression fixes.