complex-code-review

A Claude Code skill that runs a deep, multi-track code review by dispatching independent sub-agents — each an expert on one concern — and then synthesizing, de-duplicating, and adversarially verifying their findings into a single prioritized report.

The premise: a single reviewer reading a diff top-to-bottom is shallow and biased toward whatever it notices first. Splitting the review into independent, orthogonal tracks — each with its own mandate, rubric, and blind spot coverage — produces broader and deeper results. The tracks don't see each other's output until a final synthesis pass, so they can't anchor on one another.

Important

This skill is part of a development workflow, not a security audit. Its output must never be described to external parties (PR descriptions, release notes, partner comms) as "audited", "passed a security review", or similar. See CLAUDE.md.

Status

🚧 Early but functional. The skill is scaffolded — three core tracks plus two optional ones, with the core tracks baseline-tested (see the baseline-tests note below):

• SKILL.md — orchestration, shared finding schema, unified severity model.
• tracks/readability-comments.md — fully specified.
• tracks/purpose-fit.md — two-stage (spec-blind finder → informed judge) with targeted scrutiny areas; drafted.
• tracks/resilience.md — two passes (checklist-driven + workflow-backwards) with an exploitability gate; drafted. The Solidity vuln-checklist (references/vuln-checklists/solidity.md) is curated — 53 entries from SWC + not-so-smart-contracts + modern additions, each with CWE/EthTrust origin cross-refs. Other stacks: add as needed.
• tracks/spec-conformance.md — optional track (runs only when the project has a usable spec); verifies code against the Requirements-of-Record; drafted.
• tracks/documentation.md — optional, upstream step: reconciles multiple/conflicting spec docs into one authoritative Requirements-of-Record (asking the user to resolve conflicts) that spec-conformance and the purpose-fit judge consume; drafted.

Baseline tests (RED/GREEN vs real diffs): validated against review-driven commits in a real Solidity codebase (control = generic prompt, treatment = track instructions, ground truth = the review-driven fix commit):

• Purpose-fit on a contract simplification: treatment caught all three removed items (a redundant argument → a now-dead custom error → a redundant event field), correctly parked the spec-dependent ones in the uncertain bucket, and exonerated a load-bearing guard the control wrongly proposed removing. Pass.
• Readability/comments, re-baselined against a full episode (several commits — one review, not one commit): treatment flagged the off-repo-reference pattern (and correctly split durable-keep from rot-risk), and after refinement hit the exact comment-condensation targets the episode trimmed, while its noise-axis guard refused to delete Mode B tags (an over-trim that had been reverted). The accuracy axis surfaced a new High (stale interface symbol names). Pass; refinements applied and confirmed.
• Resilience on a security-relevant change: treatment found the ground-truth issue (and generalized it), with version-awareness and the exploitability gate working — and exposed that a checklist can narrow attention vs. an unconstrained reviewer, which drove a Pass-B deepening. Pass; refinement applied.

The synthesis/verification layer (cross-track dedup, the purpose-fit judge stage, the adversarial verification, REPORT/PARK/DROP disposition, and the report template) is now specified in references/synthesis.md — but not yet exercised end-to-end.

Remaining: run the full pipeline (all tracks → synthesis) end-to-end on one commit; baseline the resilience and spec-conformance tracks. Fixtures live in the gitignored .baseline/.

Review tracks

Each track is an independent sub-agent. The first three are the core set requested by the author; the rest are proposed additions (see Roadmap).

1. Readability & comments

Reviews the code as something a human has to read and maintain. Naming, structure, comment accuracy and density, comment rot, "comments that restate the code", misleading docs. (Detailed rules to be supplied by the author.)

2. Purpose-fit / anti-over-engineering

The differentiating track. The agent first states, in business terms (not code terms), what the product is supposed to do. Then it hunts for every place where the implementation is more complex than that purpose requires. Crucially, for each finding it does a root-cause pass and classifies it:

• Removable — complexity with no justification; can be simplified now.
• Spec-mandated — required by an external spec/standard/contract that can't be negotiated away (the agent cites which requirement).
• Justified-other — there is a real reason (perf, forward-compat, a non-obvious edge case, an upstream constraint). The agent records the reason so it isn't "re-discovered" and removed later.

The output is not just "this is complex" but "this is complex, here is why it exists, and here is whether that's legitimate."

3. Resilience / security ("ways to make it useless")

Broader than classic OWASP scanning. The mandate: find every way the product can be driven into a state where it stops being useful. That spans malicious input and injection, but also availability (resource exhaustion, crashes, deadlocks), data corruption, abuse/misuse, unrecoverable error states, and trust/abuse boundaries. Each finding pairs a concrete "how it breaks" scenario with a severity and a fix direction.

How it works (architecture)

                 ┌─ readability ─────────┐
   diff / branch ┼─ purpose-fit ─────────┤
   (+ RoR, if a  ┼─ resilience ──────────┼─→ synthesis ─────→ adversarial ──────→ report
    spec exists) ┼─ spec-conformance* ───┤   (dedup +         verify (skeptic →   (REPORT by
                 └─ documentation* ──────┘    judge stage)     REPORT/PARK/DROP)   severity + appendix)
   (* optional)

1. Fan-out — tracks run in parallel as independent sub-agents, each returning structured findings (no track sees another's results).
2. Synthesis — findings are de-duplicated and clustered; cross-track agreement corroborates a finding.
3. Adversarial verification → disposition — before a finding is reported, a skeptic tries to dismiss it, but only on "not real" or "no concrete consequence" (never on low importance). Each finding is then assigned REPORT / PARK / DROP — borderline ones are parked in a visible "considered" appendix rather than silently dropped, and plausible-but-unverifiable ones are self-verified, escalated to the user, or parked. Adapts the "verify before you claim" discipline from superpowers. Unlike the official code-review plugin, there's no numeric confidence gate — the disposition decides inclusion.

Roadmap

Candidate additional tracks (gaps observed in existing tooling — see comparison below):

• Behavioral test coverage — does the change have tests that survive refactoring, and what critical paths are untested? (borrow pr-test-analyzer's criticality scale, DAMP).
• Silent failures / error handling — swallowed errors, empty catches, missing logs (borrow silent-failure-hunter).
• Type design / invariants — encapsulation and invariant enforcement (borrow type-design-analyzer).
• Requirements/plan alignment → promoted to the optional spec-conformance track.

---

Comparison to other projects

A survey of the code-review tooling already installed on this machine, what each does well, and what this project borrows or improves on.

Tool	Primary use	Multi-agent	Purpose-fit / over-eng	Resilience/security	Tests	Types	False-positive filtering
complex-code-review (this)	Deep WIP/branch review	✅ tracks	✅ core, with root-cause	✅ "make it useless" framing	🔜	🔜	✅ adversarial + disposition
pr-review-toolkit	Pre-PR, multi-dimension	✅ 6 agents	partial (simplifier)	❌	✅	✅	per-agent thresholds
code-review (official)	Automated PR comments	✅ 5 agents	❌	❌	❌	❌	✅ 0–100, drop <80
security-review / code-modernization security-auditor	Security hardening	✅	❌	✅✅ OWASP/CWE	❌	❌	❌
superpowers requesting-code-review	Dev-loop review	single	partial (YAGNI)	❌	✅	❌	severity only
superpowers receiving-code-review	Handling feedback	n/a	YAGNI pushback	❌	❌	❌	n/a
code-simplifier / simplify	Post-review polish	single	✅ readability only	❌	❌	❌	❌

What the existing tools do well

• pr-review-toolkit — the closest relative. Six orthogonal expert agents (code-reviewer, code-simplifier, comment-analyzer, pr-test-analyzer, silent-failure-hunter, type-design-analyzer), each with a real rubric (e.g. test criticality 1–10, four 1–10 type axes, error-handler severity levels). Strong on tests, types, comments, error handling. Borrow: the per-track expert + rubric structure, the test and silent-failure and type agents wholesale as future tracks.
• code-review (official) — the gold standard for false-positive control: 5 parallel agents, then every issue is independently confidence-scored 0–100 and anything under 80 is dropped; uses git blame/history and prior PR comments for context; posts inline GitHub comments. Borrow (adapted): its false-positive discipline — but instead of a numeric drop-below-80 gate we use a skeptic-assigned REPORT/PARK/DROP disposition, so real findings are parked-and-visible rather than silently dropped; plus the historical-context (blame) angle. We do not borrow its inline-commenting/auto-fix automation — this skill is a deliberate, on-request review that only reports; the user decides what to act on.
• security-review / code-modernization security-auditor — disciplined OWASP Top 10 + CWE + dependency-CVE coverage, traces user input to every sink, demands a concrete exploit scenario before calling a finding real. Borrow: "assume the code is hostile", the input→sink tracing method, and "no finding without a concrete failure scenario" — fits our resilience track directly.
• superpowers requesting- / receiving-code-review — process discipline: verify a finding against the codebase before implementing it, no performative agreement, explicit YAGNI pushback. Borrow: the adversarial-verification mindset for the synthesis pass.

What they miss (our opportunity)

• No "purpose-fit" review anywhere. The closest is the simplifier's local readability pass and superpowers' YAGNI nudge. None start from a business-level statement of intent and measure the implementation against it, and none do the root-cause classification (removable vs. spec-mandated vs. justified) that prevents both needless complexity and the accidental removal of load-bearing complexity. This is our core differentiator.
• Security is siloed from general review. You either run a general reviewer or a security auditor. We fold a resilience track into the same fan-out — and frame it as "ways to make the product useless," which captures availability/abuse/corruption that pure OWASP scanning skips.
• Tooling is split by trigger, not concern. Some tools only run on an open GitHub PR (code-review), some only on the working tree (pr-review-toolkit), some only inside a modernization workflow. We target the working branch/diff directly and stay trigger-agnostic.