{
  "instruction": "Write Mongoose queries using lean() for read-only operations, runValidators on updates, and correct save() vs update patterns",
  "relevant_when": "Agent writes Mongoose queries, updates, or uses middleware",
  "context": "Use .lean() for read-only queries (5-10x faster). Always pass runValidators:true on update operations or set it globally. Pre/post save hooks only run on document.save() and Model.create(), NOT on updateOne/findByIdAndUpdate — use save() when middleware must run, or register separate update hooks.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/mongoose-best-practices/SKILL.md",
      "tile": "tessl-labs/mongoose-best-practices@0.1.3"
    }
  ],
  "checklist": [
    {
      "name": "lean-read-only",
      "rule": "Agent uses .lean() on queries whose results are read-only (API responses, templates, reports, exports)",
      "relevant_when": "Agent writes Mongoose find/query operations for read-only purposes"
    },
    {
      "name": "run-validators-on-updates",
      "rule": "Agent passes { runValidators: true } on all update operations (findByIdAndUpdate, updateOne, findOneAndUpdate, updateMany) or sets mongoose.set('runValidators', true) globally",
      "relevant_when": "Agent uses Mongoose update methods"
    },
    {
      "name": "save-vs-update-middleware",
      "rule": "Agent uses document.save() when pre/post save middleware must run, and does NOT rely on findByIdAndUpdate/updateOne to trigger save hooks. If update operations are used, agent registers separate pre('findOneAndUpdate') or pre('updateOne') hooks",
      "relevant_when": "Agent has pre-save or post-save hooks with important business logic and also uses update operations"
    },
    {
      "name": "new-true-on-find-update",
      "rule": "Agent passes { new: true } with findByIdAndUpdate/findOneAndUpdate when the updated document is needed (to return the modified document, not the original)",
      "relevant_when": "Agent uses findByIdAndUpdate or findOneAndUpdate and uses the returned document"
    }
  ]
}