update stale OCC guidance in performance audit skill (#5)

* update performance audit skill for current no-op write behavior

Replace stale no-op write guidance with invalidation-focused advice and remove outdated OCC recommendations now that unchanged writes already no-op.

Made-with: Cursor

* refine deferred work example in occ conflicts skill

Swap the scheduled work example to a clearer user-name update flow so the guidance focuses on deferring obviously secondary analytics work off the hot path.

Made-with: Cursor

Author: mikecann

skills/convex-performance-audit/SKILL.md

@@ -107,7 +107,7 @@ After finding one problem, inspect both sibling readers and sibling writers for
 Examples:
 
 - If one list query switches from full docs to a digest table, inspect the other list queries for that table
-- If one mutation needs no-op write protection, inspect the other writers to the same table
+- If one mutation isolates a frequently-updated field or splits a hot document, inspect the other writers to the same table
 - If one read path needs a migration-safe rollout for an unbackfilled field, inspect sibling reads for the same rollout risk
 
 Do not leave one path fixed and another path on the old pattern unless there is a clear product reason.
@@ -119,7 +119,7 @@ Confirm all of these:
 1. Results are the same as before, no dropped records
 2. Eliminated reads or writes are no longer in the path where expected
 3. Fallback behavior works when denormalized or indexed fields are missing
-4. New writes avoid unnecessary invalidation when data is unchanged
+4. Frequently-updated fields are isolated from widely-read documents where needed
 5. Every relevant sibling reader and writer was inspected, not just the original function
 
 ## Reference Files

skills/convex-performance-audit/references/hot-path-rules.md

@@ -241,35 +241,33 @@ const projects = await ctx.db
   .take(20);
 ```
 
-## 4. Skip No-Op Writes
+## 4. Isolate Frequently-Updated Fields
 
-No-op writes still cost work in Convex:
+Convex already no-ops unchanged writes. The invalidation problem here is real writes hitting documents that many queries subscribe to.
 
-- invalidation
-- replication
-- trigger execution
-- downstream sync
+Move high-churn fields like `lastSeen`, counters, presence, or ephemeral status off widely-read documents when most readers do not need them.
 
-Before `patch` or `replace`, compare against the existing document and skip the write if nothing changed.
-
-Apply this across sibling writers too. One careful writer does not help much if three other mutations still patch unconditionally.
+Apply this across sibling writers too. Splitting one write path does not help much if three other mutations still update the same widely-read document.
 
 ```ts
-// Bad: patching unchanged values still triggers invalidation and downstream work
-await ctx.db.patch(settings._id, {
-  theme: args.theme,
-  locale: args.locale,
+// Bad: every presence heartbeat invalidates subscribers to the whole profile
+await ctx.db.patch(user._id, {
+  name: args.name,
+  avatarUrl: args.avatarUrl,
+  lastSeen: Date.now(),
 });
 ```
 
 ```ts
-// Good: only write when something actually changed
-if (settings.theme !== args.theme || settings.locale !== args.locale) {
-  await ctx.db.patch(settings._id, {
-    theme: args.theme,
-    locale: args.locale,
-  });
-}
+// Good: keep profile reads stable, move heartbeat updates to a separate document
+await ctx.db.patch(user._id, {
+  name: args.name,
+  avatarUrl: args.avatarUrl,
+});
+
+await ctx.db.patch(presence._id, {
+  lastSeen: Date.now(),
+});
 ```
 
 ## 5. Match Consistency To Read Patterns

skills/convex-performance-audit/references/occ-conflicts.md

@@ -73,42 +73,30 @@ await ctx.db.patch(shardId, { count: shard!.count + 1 });
 
 Aggregate the shards in a query or scheduled job when you need the total.
 
-### 3. Skip no-op writes
+### 3. Move non-critical work to scheduled functions
 
-Writes that do not change data still participate in conflict detection and trigger invalidation.
+If a mutation does primary work plus secondary bookkeeping (analytics, non-critical notifications, cache warming), the bookkeeping extends the transaction's lifetime and read/write set.
 
 ```ts
-// Bad: patches even when nothing changed
-await ctx.db.patch(doc._id, { status: args.status });
-```
-
-```ts
-// Good: only write when the value actually differs
-if (doc.status !== args.status) {
-  await ctx.db.patch(doc._id, { status: args.status });
-}
-```
-
-### 4. Move non-critical work to scheduled functions
-
-If a mutation does primary work plus secondary bookkeeping (analytics, notifications, cache warming), the bookkeeping extends the transaction's lifetime and read/write set.
-
-```ts
-// Bad: analytics update in the same transaction as the user action
-await ctx.db.patch(userId, { lastActiveAt: Date.now() });
-await ctx.db.insert("analytics", { event: "action", userId, ts: Date.now() });
+// Bad: canonical write and derived work happen in the same transaction
+await ctx.db.patch(userId, { name: args.name });
+await ctx.db.insert("userUpdateAnalytics", {
+  userId,
+  kind: "name_changed",
+  name: args.name,
+});
 ```
 
 ```ts
-// Good: schedule the bookkeeping so the primary transaction is smaller
-await ctx.db.patch(userId, { lastActiveAt: Date.now() });
-await ctx.scheduler.runAfter(0, internal.analytics.recordEvent, {
-  event: "action",
+// Good: keep the primary write small, defer the analytics work
+await ctx.db.patch(userId, { name: args.name });
+await ctx.scheduler.runAfter(0, internal.users.recordNameChangeAnalytics, {
   userId,
+  name: args.name,
 });
 ```
 
-### 5. Combine competing writes
+### 4. Combine competing writes
 
 If two mutations must update the same document atomically, consider whether they can be combined into a single mutation call from the client, reducing round trips and conflict windows.