用途：诊断并修复 Convex 应用的性能问题，按问题类别逐一处理。当 Convex 页面或功能变慢、开销偏高，或 npx convex insights --details 报告高读取字节数、读取文档数、OCC 冲突，以及低时效性读取路径误用响应式、订阅数过高、UI 更新缓慢、函数接近执行或事务限制时适用。纯 schema 迁移、初始搭建或无实际信号的一次性微优化不建议使用。
主要能力：先收集信号，优先使用部署健康洞察或 CLI 洞察，必要时运行 npx convex insights --details（可用 --prod、--preview-name、--deployment-name）；本地 CLI 过旧时可尝试 npx -y convex@latest insights --details。若已有 convex-doctor 结果，仅作线索。无运行时信号也可从代码审计，但需注意缺少洞察不等于健康，也不代表需要大重构。
按信号路由到参考文件：高读取/JS 过滤/多余 join 用 references/hot-path-rules.md；OCC 冲突、写争用、mutation 重试用 references/occ-conflicts.md；订阅过多、UI 慢、过度重渲染用 references/subscription-cost.md；函数超时、事务过大、载荷过大用 references/function-budget.md；笼统变慢先看 hot-path-rules。多类问题可重叠，先读最相关者。
使用方式：先界定一个具体用户流程，记录入口函数、客户端 useQuery/usePaginatedQuery/useMutation 调用点、读写表；再追踪每个函数中的 ctx.db.get()、ctx.db.query() 以及 ctx.db.patch()、ctx.db.replace()、ctx.db.insert()，注意外键查询、JS 侧过滤和整文档读取，并找出操作同表的兄弟函数与同页响应式统计组件；随后按参考文件的修复顺序处理，并一并修复兄弟读写函数；最后验证结果一致、无丢记录、回退可用、无变化写入不产生多余失效。
限制与升级：小规模、低流量或信号弱时优先简单代码；无实测信号、无明确无界路径或已知热读写路径时，不建议摘要表、文档拆分、抓取策略改动或迁移重的方案。小而简单的扫描通常可接受。若修复具侵入性、跨切面或迁移重，先停下给出选项，例如引入摘要表、拆分高频更新字段、重做分页或抓取策略、切换索引或需迁移安全上线的反范式字段；涉及新旧状态兼容时参考 skills/convex-migration-helper/SKILL.md。可另查阅官方 Convex 最佳实践页。