feat(partition): add query-pattern tie-breaker guidance

skills/cosmosdb-best-practices/rules/partition-high-cardinality.md

@@ -77,4 +77,14 @@ Good partition keys typically:
 - Match your most common query patterns
 - Distribute writes evenly (no single key dominates)
 
+### Cardinality vs. Query Patterns
+
+High cardinality is important for even distribution, but it should not be the sole factor when selecting a partition key.
+
+For read-heavy workloads that can grow to multiple physical partitions and where most queries use an equality filter on a specific field, prefer a partition key aligned with that dominant query pattern even if its cardinality is lower than `/id`, as long as it still provides sufficient cardinality to avoid hot partitions. If the query-aligned field is too low-cardinality, consider a synthetic or hierarchical partition key to preserve query alignment while improving distribution.
+
+A bare `/id` partition key is most appropriate when point reads by `/id` are the dominant access pattern, when the container is small enough to remain within a single physical partition, or when write throughput requires maximum distribution. If the dominant query pattern filters on another field, consider whether aligning the partition key with that field would reduce cross-partition queries.
+
+See also: `partition-query-patterns`.
+
 Reference: [Partitioning in Azure Cosmos DB](https://learn.microsoft.com/azure/cosmos-db/partitioning-overview)

skills/cosmosdb-best-practices/rules/partition-query-patterns.md

@@ -83,4 +83,14 @@ public class Message
 // "Get messages in conversation" - single partition, fast
 ```
 
+### Query Alignment vs. Cardinality
+
+When query-pattern guidance conflicts with pure cardinality guidance, favor the partition key that supports the dominant access pattern, especially for read-heavy workloads that can grow to multiple physical partitions.
+
+For example, if most queries use an equality filter on `/category` (and `category` has sufficient cardinality to avoid hot partitions), partitioning by `/category` may be preferable to partitioning by `/id`, even though `/id` provides higher cardinality. This keeps the dominant queries single-partition (when you supply the `PartitionKey` value) and avoids unnecessary cross-partition fan-out.
+
+If `/category` has insufficient cardinality and may create hot partitions, consider a synthetic or hierarchical partition key that preserves query alignment while improving distribution.
+
+See also: `partition-high-cardinality`.
+
 Reference: [Choose a partition key](https://learn.microsoft.com/azure/cosmos-db/partitioning-overview#choose-a-partition-key)