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