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.mdskills/data/n-plus-one-hunter/SKILL.md
GitHubWhat 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
- If
-helpis passed, print the## Usageblock below and stop.
Step 2
- Confirm
-ProjectDiris provided and the path exists.
Step 3
- Run:
scripts/loop-query-trace.ps1 -ProjectDir "<path>"
Step 4
- LLM reads the JSON output. For each candidate:
Step 5
- Read the
loopType,loopSource, andqueryCallfields.
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
- Confidence:
proven(query inside loop with no batch hint),likely
Step 10
(query inside loop with partial batch hint), suspected (ambiguous).
Step 11
- Write
n-plus-one-report.mdto 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)