n-plus-one-hunter

N+1 query hunter: traces loop-to-query data flows in source code, identifies ORM N+1 patterns, and distinguishes real N+1 problems from intentional batch/join patterns. Read-only. Audience: Both. Trig

SKILL.md

GitHub

What this is for

ORM N+1 queries are the #1 performance antipattern in web applications. A loop that fetches 100 parent rows then executes 100 more queries for each child produces 101 database round-trips where 1 would suffice. This skill finds the pattern statically by tracing loop constructs to ORM data-access calls, then the LLM distinguishes real N+1 problems from intentional batch patterns.

The dominant failure mode is the hidden N+1 that degrades production performance linearly with data growth - invisible in development with small datasets.

PROTECTION RULE - never ~/.claude/

Read-only skill. Guard required if write mode added later.

## What You Must Do When Invoked

Step 1

  1. If -help is passed, print the ## Usage block below and stop.

Step 2

  1. Confirm -ProjectDir is provided and the path exists.

Step 3

  1. Run: scripts/loop-query-trace.ps1 -ProjectDir "<path>"

Step 4

  1. LLM reads the JSON output. For each candidate:

Step 5

  • Read the loopType, loopSource, and queryCall fields.

Step 6

  • Check hasBatchHint: does the query use IN clause, whereIn, include, or relations?

Step 7

  • If hasBatchHint is false and the query is inside a loop: real N+1.

Step 8

  • If hasBatchHint is true: intentional batch or eager-loaded pattern.

Step 9

  1. Confidence: proven (query inside loop with no batch hint), likely

Step 10

(query inside loop with partial batch hint), suspected (ambiguous).

Step 11

  1. Write n-plus-one-report.md to the working directory.

Usage

/n-plus-one                         # interactive, prompts for directory
/n-plus-one <dir>                   # scan project directory
/n-plus-one -help                   # show usage

Returns JSON with candidates[]: each entry {file, line, loopType, loopSource, queryCall, queryArgs, hasBatchHint} plus counts: {scannedFiles, totalCandidates, byVerdict}.

Report Format

n-plus-one-report.md with:

  • Executive summary (total candidates, real N+1 vs batch vs eager-loaded)
  • Critical findings (real N+1 - O(n) queries where O(1) would work)
  • Non-issues (batch queries and eager-loaded relations)
  • Confidence column for every finding
  • Open questions (suspected, needs human review)