ln-812-query-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，然后向上一级即可到达仓库根目录。

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).

类型： L3 Worker 分类： 8XX 优化 父级： ln-810-performance-optimization-coordinator

修复由ln-651-query-efficiency-auditor检测到的查询效率问题。每个修复都会通过保留/丢弃模式的测试进行验证。衡量指标：查询数量减少（而非运行时基准测试）。

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)

维度	详情
输入	来自 `docs/project/persistence_audit.md` （ln-651章节）的审计检测结果，或目标文件
输出	优化后的查询语句、验证报告
配套工具	ln-651-query-efficiency-auditor（检测问题）→ ln-812（修复问题）

Workflow

工作流程

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

阶段： 预检查 → 加载检测结果 → 优先级排序 → 修复循环 → 生成报告

Phase 0: Pre-flight Checks

阶段0：预检查

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.

检查项	是否必填	缺失时操作
审计检测结果或目标文件	是	终止优化操作
测试基础设施	是	终止操作（需要测试来验证修复）
Git 干净状态	是	终止操作（需要干净的基线用于回滚）

必读内容： 加载

shared/references/ci_tool_detection.md

— 使用其中的「测试框架」部分进行测试检测。

Worktree & Branch Isolation

工作树与分支隔离

MANDATORY READ: Load

shared/references/git_worktree_fallback.md

— use ln-812 row.

必读内容： 加载

shared/references/git_worktree_fallback.md

— 使用其中的ln-812行内容。

Phase 1: Load Findings

阶段1：加载检测结果

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

读取

docs/project/persistence_audit.md

，提取ln-651的检测结果：

问题类型	优化方案
N+1查询	批量加载/预加载/ `.Include()` / `prefetch_related`
冗余获取	传递对象而非ID，缓存结果
过度获取	选择特定字段/投影/ `.Select()`
缺少索引提示	添加索引注解/迁移
无界查询	添加 `.Take()` / `LIMIT` /分页

From Target File

从目标文件加载

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

如果没有审计报告：扫描目标文件，查找与上表匹配的查询模式。

Phase 2: Prioritize Fixes

阶段2：修复优先级排序

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

优先级	判定标准
1（最高）	热路径中的N+1查询（每次请求都会调用）
2	冗余获取（同一实体被多次加载）
3	过度获取（需要少量列却使用SELECT *）
4	用户面向端点缺少分页

Phase 3: Fix Loop (Keep/Discard)

阶段3：修复循环（保留/丢弃）

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

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.

条件	决策
没有测试覆盖受影响的文件/函数	跳过该问题 — 记录为「未覆盖，已跳过」
测试通过	保留修复
测试失败	丢弃修复并记录失败原因
修复引入新的N+1查询	丢弃修复

注意： 无需进行基准测试 — 查询优化的衡量标准是正确性（测试通过）+ 结构改进（查询数量减少）。审计环节已经识别出低效问题。

Phase 4: Report Results

阶段4：生成结果报告

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

字段	描述
source	审计报告路径或目标文件
findings_total	审计检测到的问题总数
fixes_applied	成功保留的修复数量
fixes_discarded	已丢弃的修复及原因
fix_details[]	单修复详情：问题类型、文件、修复前后描述

Configuration

配置

yaml

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

yaml

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

错误类型	原因	解决方案
无审计检测结果	ln-651未运行或未检测到问题	报告「无需要优化的检测结果」
ORM特定语法	未知ORM	查询Context7/Ref获取ORM文档
需要迁移	添加索引需要执行迁移	记录为手动步骤，跳过该修复

References

参考资料

../ln-651-query-efficiency-auditor/SKILL.md

(companion: finds issues)

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

../ln-651-query-efficiency-auditor/SKILL.md

（配套工具：检测问题）

```
shared/references/ci_tool_detection.md
```
（测试检测）

版本： 1.0.0 最后更新： 2026-03-08

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

—