{
  "instruction": "Use correct Mongoose architectural patterns: embed vs populate, cursor pagination, transactions, and connection handling",
  "relevant_when": "Agent designs Mongoose data models, implements pagination, handles multi-document operations, or configures database connections",
  "context": "Embed bounded child data that belongs to the parent; reference shared/unbounded data. Use cursor-based pagination (not skip/limit) for large collections. Use transactions (startSession + withTransaction) for multi-document atomic operations, passing { session } to every operation. Configure connections with maxPoolSize, error handlers, and graceful shutdown.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/mongoose-best-practices/SKILL.md",
      "tile": "tessl-labs/mongoose-best-practices@0.1.3"
    }
  ],
  "checklist": [
    {
      "name": "embed-vs-populate",
      "rule": "Agent embeds bounded child data that belongs to the parent (e.g., address in user, line items in order) rather than creating unnecessary separate collections. Agent uses references/populate only for shared, unbounded, or independently-queried data",
      "relevant_when": "Agent designs data models with related data"
    },
    {
      "name": "cursor-pagination",
      "rule": "Agent uses cursor-based pagination (filtering on an indexed field like _id) instead of skip/limit for large or growing collections",
      "relevant_when": "Agent implements pagination for potentially large datasets"
    },
    {
      "name": "transactions-for-atomicity",
      "rule": "Agent uses mongoose.startSession() and session.withTransaction() for operations that must atomically update multiple documents, passing { session } to every operation inside the transaction",
      "relevant_when": "Agent needs to update multiple documents atomically (e.g., transfers, order processing)"
    },
    {
      "name": "transaction-session-cleanup",
      "rule": "Agent calls session.endSession() in a finally block after using transactions",
      "relevant_when": "Agent uses MongoDB transactions"
    },
    {
      "name": "connection-config",
      "rule": "Agent configures mongoose.connect with maxPoolSize, serverSelectionTimeoutMS, error event handlers, and graceful shutdown (closing connection on SIGTERM/SIGINT)",
      "relevant_when": "Agent sets up Mongoose connection"
    }
  ]
}