Logic-Lens

Logic-first code review using semi-formal execution tracing.
Finds behavioral bugs that linters, type checkers, and unstructured review miss.

Nine Risks • Example • Six Skills • Benchmark • Installation • Usage • Configuration • Contributing

"Models using structured (semi-formal) reasoning achieve 87–93% accuracy on code semantics tasks, versus 76–78% for unstructured chain-of-thought — with the largest gains on interprocedural bugs." — Ugare & Chandra, Agentic Code Reasoning (2026, arXiv:2603.01896)

Code review without a trace is a guess. Standard review catches style issues and obvious mistakes. Linters catch syntax. But neither catches the class of bugs where code looks correct in isolation, passes all tests, and still ships broken behavior — because the bug only appears when two functions interact in a way neither author anticipated.

Logic-Lens forces the AI to construct an explicit execution trace before reaching any conclusion. Every finding comes with a documented Premises → Trace → Divergence → Trigger → Remedy chain that shows exactly how the reviewer arrived at the finding — not just what it found.

The Nine Logic Risks

Logic-Lens evaluates code across nine logic risk dimensions — six derived from the semi-formal reasoning methodology in Agentic Code Reasoning (L1–L6), plus three covering modern hazards that fall outside the paper's single-process scope (L7–L9):

What It Looks Like

Given this code:

def process_order(order_id, items, discount_code=None):
    order = db.get_order(order_id)
    total = sum(item['price'] * item['qty'] for item in items)

    if discount_code:
        discount = coupon_service.get_discount(discount_code)
        total = total * (1 - discount)

    order['total'] = total
    order['items'] = items
    db.save_order(order)
    email_service.send_confirmation(order['email'], total)

Logic-Lens produces:

Logic Health: 31/100

This function contains a callee contract mismatch that causes a silent divide-by-zero risk, a boundary blindspot on empty item lists, and a resource lifecycle hazard that leaks a database connection on email failure.

🔴 L6 — Callee Contract Mismatch: get_discount May Return None

Premises: coupon_service.get_discount(code) is assumed to always return a numeric discount rate between 0 and 1. Trace: discount_code is truthy → get_discount(discount_code) is called → result assigned to discount → total * (1 - discount) is evaluated. Divergence: get_discount returns None for expired or invalid codes (documented in its docstring). When discount is None, 1 - None raises TypeError. The call reaches db.save_order only on the happy path; a bad coupon code aborts the function without saving. Trigger: process_order(1, [{'price': 10, 'qty': 1}], discount_code='EXPIRED2024') → TypeError: unsupported operand type(s) for -: 'int' and 'NoneType'; order never saved. Remedy: Check if discount is not None: before applying. Alternatively, have get_discount raise a typed exception (InvalidCouponError) that the caller can handle explicitly.

🔴 L3 — Boundary Blindspot: Empty items List

Premises: items is assumed to contain at least one element. Trace: sum(item['price'] * item['qty'] for item in items) → returns 0 for empty list → total = 0 → order['total'] = 0 → saved and confirmed. Divergence: An order with zero items is silently saved as a $0.00 order and a confirmation email is sent. No business rule validates that an order must contain at least one item. Trigger: process_order(1, []) → expected a rejection; actual: order persisted with total = 0 and a confirmation email dispatched. Remedy: Add if not items: raise ValueError("Order must contain at least one item") before the sum. This is a business invariant, not an implementation detail.

🟡 L8 — Resource Lifecycle Hazard: Database Connection Not Released on Email Failure

Premises: db.save_order and email_service.send_confirmation are assumed to both succeed. Trace: db.save_order(order) succeeds → connection kept open → email_service.send_confirmation(...) raises SMTPException → function exits via uncaught exception. Divergence: The database connection is never explicitly released. Depending on the ORM's connection pooling strategy, this may exhaust the pool under sustained email failure. Trigger: Stub email_service.send_confirmation to raise SMTPException, then call process_order once per pool slot — the pool is exhausted and the next call blocks on checkout. Remedy: Wrap email_service.send_confirmation in a try/finally block, or separate the email send into an async queue so order persistence is not coupled to email delivery.

(+ 2 more findings)

Quickstart (60 seconds)

Claude Code users:

/plugin marketplace add hyhmrright/logic-lens
/plugin install logic-lens@logic-lens-marketplace
/logic-review

Then paste any function. Done. (Short-form commands like /logic-review are auto-installed on first session start.)

For Gemini CLI and Codex CLI, see Installation below.

Six Skills

Logic-Lens ships six skills: logic-review (find behavioral bugs via execution tracing), logic-explain (trace what code actually does step by step), logic-diff (verify two versions are behaviorally equivalent), logic-locate (find the root cause of a failing test or crash), logic-health (aggregate logic health dashboard across a codebase), and logic-fix-all (autonomous audit-and-fix pipeline — after consent, scans the target, applies fixes for every finding, verifies each fix, and reports anything unresolved). See Usage for per-skill commands and Slash Commands for platform-specific syntax.

Benchmark

Logic-Lens is scored against evals/content/v2/evals-v2.json — 104 cases across the six skills, spanning 12+ languages, with cases modeled on Defects4J, QuixBugs, the Therac-25 and Ariane 5 inquiries, and Lu et al.'s concurrency-bug study. Every run is graded offline by a rule-based grader (scripts/grade-iteration.py), not by an LLM judge.

Published logic-review runs (36-case subset, claude-sonnet-4-6):

Every frozen run summary is in benchmarks/runs/, cataloged by benchmarks/index.json, with human-readable reports under benchmarks/reports/. Reproduce any of them with npm run content-evals.

How to read these numbers. The grader splits each case into a logic sub-score (did it find the bug and classify the risk correctly?) and a contract sub-score (does the report carry the literal Iron Law field labels?). overall_pass_rate mixes both, and contract assertions are ~25% of the total — so overall is a combined record, not a pure measure of reasoning quality. See benchmarks/README.md for the metric hierarchy and the multi-run averaging rule (single-run case-level deltas have been observed to swing ±25pp).

What is not measured here. There is no published head-to-head against unassisted Claude in this repo; the version-over-version numbers above are the honest claim. Results also depend heavily on the host model actually invoking the skill — see docs/MODEL_COMPATIBILITY.md, where Haiku in claude -p mode scores 38.7% almost entirely because it answers directly without loading the skill.

How It Compares

~ = occasionally / inconsistently

Logic-Lens doesn't replace your linter. It catches what linters can't: callee contract violations, state mutation hazards, and control flow escapes — the bugs that cause production incidents in syntax-clean, lint-passing code.

Installation

Claude Code (Recommended)

Already ran the Quickstart? You're done — skip to Slash Commands.

Via Plugin Marketplace

/plugin marketplace add hyhmrright/logic-lens
/plugin install logic-lens@logic-lens-marketplace

Short-form commands (/logic-review) are auto-installed on first session start. To install manually:

cp commands/*.md ~/.claude/commands/

Manual Install

mkdir -p ~/.claude/skills/logic-lens
cp -r skills/* ~/.claude/skills/logic-lens/

Gemini CLI

Via Extension

/extensions install https://github.com/hyhmrright/logic-lens

Manual Install

mkdir -p ~/.gemini/skills/logic-lens
cp -r skills/* ~/.gemini/skills/logic-lens/

Codex CLI

Via Skill Installer (in Codex session)

Install the logic-lens skill from hyhmrright/logic-lens

Command Line

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo hyhmrright/logic-lens --path skills --name logic-lens

Manual Install

git clone https://github.com/hyhmrright/logic-lens.git /tmp/logic-lens
mkdir -p ~/.codex/skills/logic-lens
cp -r /tmp/logic-lens/skills/* ~/.codex/skills/logic-lens/

Slash Commands

The same six skills, invoked with each platform's prefix:

• Claude Code also accepts the fully-qualified form /logic-lens:logic-review. The short forms are auto-installed on first session start by the session-start hook (macOS, Linux, and Windows via WSL / Git Bash).
• Codex CLI: enter $logic-* inside a Codex session — these are not shell commands.

Usage

Invocation syntax is in Slash Commands above. What each skill does with your input:

logic-review — Code Logic Review

Paste the code or point the AI at the file. Logic-Lens constructs an explicit execution trace for each suspicious path and reports only findings with a documented Premises → Trace → Divergence → Trigger → Remedy chain.

logic-explain — Execution Explanation

Ask "what does this code actually do?" and get a step-by-step trace that crosses function boundaries, rather than a natural-language summary of what the code appears to do.

logic-diff — Semantic Diff

Paste two versions of a function. Logic-Lens traces both and reports whether they are behaviorally equivalent — and if not, exactly which execution path produces a different outcome.

logic-locate — Fault Localization

Paste a failing test, stack trace, or bug report alongside the relevant code. Logic-Lens traces backward from the failure to identify the exact divergence point — distinguishing root cause from symptom.

logic-health — Logic Health Dashboard

Runs abbreviated logic reviews across a codebase and produces a weighted Logic Health Score (0–100) broken down by risk dimension. Use before a release, during an audit, or when onboarding onto an unfamiliar codebase.

logic-fix-all — Autonomous Audit-and-Fix

Point it at a directory or file. Logic-Lens first asks for consent because this mode is token-intensive and edits files. After consent, it sweeps the scope, collects findings at every severity level (L1–L9), applies fixes in priority order, verifies each fix with a semantic diff, and re-confirms the codebase is clean unless it reaches the configured iteration cap or a design decision is required. The final output is a Fix Log table listing every change made and its verification status.

Configuration

Place a .logic-lens.yaml in your project root to customize behavior:

# Skip concurrency checks in confirmed single-threaded code
disable:
  - L7

# Treat all boundary issues as critical for this safety-critical module
severity:
  L3: critical

# Exclude generated files and vendor code from analysis
ignore:
  - "tests/fixtures/**"
  - "vendor/**"
  - "**/*.generated.*"

All settings are optional — omit the file entirely for default behavior.

Language Support

Logic-Lens is language-agnostic. The semi-formal reasoning methodology applies to any language where name resolution, type contracts, and execution paths can be traced by reading source code. The shared guide includes language-specific tracing notes for:

Python · JavaScript / TypeScript · Java / Kotlin · Go · Rust · SQL

Other languages work with the general methodology — scope chain rules, type coercion behavior, and exception propagation semantics are the only language-specific knowledge required.

How It Works

Logic-Lens does not execute code or use static analysis tools. It works by prompting the AI to follow a structured reasoning template that mirrors the semi-formal methodology from Agentic Code Reasoning (Ugare & Chandra, 2026).

The key insight from the paper: when models are forced to state premises explicitly before tracing, they catch interprocedural bugs at 87–93% accuracy. Without the structure, the same models miss these bugs 22–24% of the time — because they pattern-match on code appearance rather than reasoning through execution.

The discipline enforced per finding:

1. Premises — State every assumption about name resolution, types, and preconditions
2. Trace — Follow the actual execution path step by step, crossing function boundaries
3. Divergence — Identify the exact point where a premise breaks and what follows
4. Trigger — Give a concrete input that reproduces it, specific enough to paste into a REPL
5. Remedy — Prescribe a fix that addresses the divergence, not just its symptom

No Trigger or Remedy may be written before Premises → Trace → Divergence is complete. This is the Iron Law of Logic-Lens. (Trigger is required for Critical and Warning findings, optional for Suggestions.)

Project Structure

logic-lens/
├── .claude-plugin/              # Claude Code plugin metadata
├── .codex-plugin/               # Codex CLI plugin metadata
├── gemini-extension.json        # Gemini CLI extension metadata
├── skills/
│   ├── _shared/                  # Shared framework files
│   │   ├── common.md             # Language rule, Iron Law, Logic Score, yaml schema
│   │   ├── logic-risks.md        # L1–L9 risk taxonomy with examples
│   │   ├── semiformal-guide.md   # Execution tracing methodology + min thresholds
│   │   ├── semiformal-checklist.md  # Premises Construction Checklist (single source)
│   │   └── report-template.md    # Report Template (English + Chinese, single source)
│   ├── logic-review/             # Skill 1: Code logic review
│   ├── logic-explain/            # Skill 2: Execution explanation
│   ├── logic-diff/               # Skill 3: Semantic diff
│   ├── logic-locate/             # Skill 4: Fault localization
│   ├── logic-health/             # Skill 5: Health dashboard
│   └── logic-fix-all/            # Skill 6: Autonomous audit-and-fix
│       ├── SKILL.md
│       ├── logic-fix-all-guide.md  # Navigation + shared context
│       ├── guide-phases-0-2-consent-scope-health.md
│       ├── guide-phases-3-5-review-locate-clarify.md
│       └── guide-phases-6-9-fix-iterate-report.md
├── commands/                     # Short-form command wrappers (auto-installed by hook)
├── hooks/                        # Session-start hook
├── evals/
│   ├── content/v2/evals-v2.json  # Content eval cases (104 cases — the benchmark suite)
│   ├── trigger/v2/trigger-evals-*.json  # Per-skill trigger eval sets (6 × 20 cases)
│   ├── real-world/               # Real-code probes — second verification line, incl. decoys
│   └── v1/                       # Legacy v1 cases, archived
├── benchmarks/
│   ├── index.json                # Catalog of published runs
│   ├── runs/                     # Frozen run summaries (JSON)
│   └── reports/                  # Human-readable reports, per version tag
├── scripts/                      # Dev utilities (validate, run-content-evals, grade-iteration)
├── tests/                        # Python unit tests for the grader
├── docs/                         # Model compatibility, research references, case studies
└── CONTRIBUTING.md

Why Semi-Formal Reasoning?

AI-assisted development is making codebases grow faster than human review capacity. The bugs that slip through are increasingly the interprocedural kind — the ones that require holding two functions' contracts in mind simultaneously and noticing when they don't match.

"The bearing of a child takes nine months, no matter how many women are assigned." — Frederick Brooks, The Mythical Man-Month (1975)

Adding AI reviewers doesn't fix the problem if they make the same reasoning errors as human reviewers: pattern-matching on surface appearance, anchoring on the happy path, skipping the trace when the code "looks fine." Logic-Lens addresses this at the methodology level — not by prompting the AI to "be more careful," but by structuring the reasoning process so it cannot skip the step where bugs hide. Published benchmark summaries live in benchmarks/runs/.

Contributing

See CONTRIBUTING.md. Logic-Lens is designed for universal use — contributions must not embed assumptions about any particular language, framework, or development workflow.

The best contributions right now are new eval test cases, especially interprocedural bugs drawn from real production incidents. See CONTRIBUTING.md for the format.

New to the project? The fastest way to contribute is a new eval test case — see the issue template.

Spread the Word

If Logic-Lens saves you from a production incident, let others know!

• Share on X (Twitter): Click to tweet
• Add a Badge: Show that your repository is logic-reviewed by adding this badge to your README:

  [![Logic-Lens: Audited](https://img.shields.io/badge/Logic--Lens-Audited-blueviolet.svg)](https://github.com/hyhmrright/logic-lens)
  

Read

• Why AI Code Review Misses Logic Bugs — And How Structured Execution Tracing Fixes It — DEV.to deep-dive on the methodology behind logic-lens

License

MIT License — see LICENSE for details.

Acknowledgments

Logic-Lens is grounded in the following research:

• Ugare & Chandra — Agentic Code Reasoning (2026, arXiv:2603.01896)

The semi-formal reasoning methodology, risk taxonomy, and accuracy benchmarks referenced throughout this project are derived from or inspired by this work.

⭐ If Logic-Lens helped you catch a bug before it shipped, give it a star!

Star History