Paths: File paths (shared/ , references/ , ../ln-* ) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

ln-812-query-optimizer

Type: L3 Worker Category: 8XX Optimization Parent: ln-810-performance-optimization-coordinator

Fixes query efficiency issues found by ln-651-query-efficiency-auditor. Each fix verified via tests with keep/discard pattern. Metric: query count reduction (not runtime benchmark).

Overview

Aspect Details

Input Audit findings from docs/project/persistence_audit.md (ln-651 section) OR target file

Output Optimized queries, verification report

Companion ln-651-query-efficiency-auditor (finds issues) → ln-812 (fixes them)

Workflow

Phases: Pre-flight → Load Findings → Prioritize → Fix Loop → Report

Phase 0: Pre-flight Checks

Check Required Action if Missing

Audit findings OR target file Yes Block optimization

Test infrastructure Yes Block (need tests for verification)

Git clean state Yes Block (need clean baseline for revert)

MANDATORY READ: Load shared/references/ci_tool_detection.md — use Test Frameworks section for test detection.

Worktree & Branch Isolation

MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-812 row.

Phase 1: Load Findings

From Audit Report

Read docs/project/persistence_audit.md , extract ln-651 findings:

Finding Type Optimization

N+1 query Batch loading / eager loading / .Include() / prefetch_related

Redundant fetch Pass object instead of ID, cache result

Over-fetching Select specific fields / projection / .Select()

Missing index hint Add index annotation / migration

Unbounded query Add .Take() / LIMIT / pagination

From Target File

If no audit report: scan target file for query patterns matching the table above.

Phase 2: Prioritize Fixes

Priority Criteria

1 (highest) N+1 in hot path (called per request)

2 Redundant fetches (same entity loaded multiple times)

3 Over-fetching (SELECT * where few columns needed)

4 Missing pagination on user-facing endpoints

Phase 3: Fix Loop (Keep/Discard)

Per-Fix Cycle

FOR each finding (F1..FN):

1. APPLY: Edit query code (surgical change)
2. VERIFY: Run tests IF tests FAIL → DISCARD (revert) → next finding
3. VERIFY: Tests PASS → KEEP
4. LOG: Record fix for report

Keep/Discard Decision

Condition Decision

No tests cover affected file/function SKIP finding — log as "uncovered, skipped"

Tests pass KEEP

Tests fail DISCARD + log failure reason

Fix introduces new N+1 DISCARD

Note: No benchmark needed — query optimization metric is correctness (tests pass) + structural improvement (fewer queries). The audit already identified the inefficiency.

Phase 4: Report Results

Report Schema

Field Description

source Audit report path or target file

findings_total Total findings from audit

fixes_applied Successfully kept fixes

fixes_discarded Failed fixes with reasons

fix_details[] Per-fix: finding type, file, before/after description

Configuration

Options:

Source

audit_report: "docs/project/persistence_audit.md" target_file: "" # Alternative to audit report

Verification

run_tests: true

Scope

fix_types: # Filter which types to fix - n_plus_one - redundant_fetch - over_fetching - unbounded_query

Error Handling

Error Cause Solution

No audit findings ln-651 not run or no issues Report "no findings to optimize"

ORM-specific syntax Unknown ORM Query Context7/Ref for ORM docs

Migration needed Index addition requires migration Log as manual step, skip

References

• ../ln-651-query-efficiency-auditor/SKILL.md (companion: finds issues)

• shared/references/ci_tool_detection.md (test detection)

Definition of Done

• Findings loaded from audit report or target file scan

• Fixes prioritized (N+1 first, then redundant, over-fetch, unbounded)

• Each fix applied with keep/discard: tests pass → keep, tests fail → discard

• No new query inefficiencies introduced by fixes

• Report returned with findings total, fixes applied, fixes discarded

Version: 1.0.0 Last Updated: 2026-03-08