Add integrated cache best practice rule

[Bhuvansh (BHUVANSH855)]

Description

Adds a new best practice rule recommending the use of Azure Cosmos DB Integrated Cache for read-heavy workloads. The rule explains when Integrated Cache should be used, highlights the dedicated gateway requirement, demonstrates configuring MaxIntegratedCacheStaleness, and outlines the supported consistency levels. It also adds the new rule to the Cosmos DB Best Practices skill index.

Type of Change

• 📝 New rule - Adding a new best practice rule
• ✏️ Rule improvement - Updating an existing rule
• 🆕 New skill - Adding an entirely new skill
• 🐛 Bug fix - Fixing an issue with existing content
• 📚 Documentation - Updating README, CONTRIBUTING, or other docs
• 🔧 Build/Scripts - Changes to build process or scripts

Checklist

• I have read the Contributing Guide
• I ran npm run validate and it passed
• My rule file follows the naming convention: {prefix}-{description}.md
• My rule includes valid frontmatter (title, impact, tags)

For New Rules

Rule file: skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md

Category: Throughput & Scaling

Impact level: Medium

Why is this rule important?

Read-heavy workloads often perform repeated point reads or queries for the same data. Azure Cosmos DB Integrated Cache can significantly reduce RU consumption and improve latency by serving cached results through the dedicated gateway. This rule helps developers understand when Integrated Cache is appropriate, how to configure MaxIntegratedCacheStaleness, and the consistency requirements for using the feature effectively.

Agent Testing

• Tested with GitHub Copilot
• Tested with Claude Code
• Tested with Cursor
• Tested with other agent: _____
• N/A (documentation only)

Related Issues

Closes #172

Additional Notes

• Added a new throughput best practice rule for Azure Cosmos DB Integrated Cache.
• Updated skills/cosmosdb-best-practices/SKILL.md to include the new rule.
• Verified the changes with:
  • npm run build
  • npm run validate
  • npm run validate:manifests

[Copilot]

Pull request overview

This PR expands the cosmosdb-best-practices skill by adding a new Throughput & Scaling rule that recommends Azure Cosmos DB Integrated Cache (via dedicated gateway) for read-heavy workloads, and it wires the new rule into the skill index.

Changes:

• Added a new rule file throughput-integrated-cache.md describing when/how to use Integrated Cache, including MaxIntegratedCacheStaleness guidance and consistency constraints.
• Updated SKILL.md to include the new rule in the Throughput & Scaling section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
skills/cosmosdb-best-practices/SKILL.md	Adds the new throughput rule to the skill’s indexed rule list.
skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md	Introduces a new best-practice rule for using Integrated Cache with dedicated gateway, including Incorrect/Correct examples and reference link.

Comments suppressed due to low confidence (1)

skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md:33

• The “Correct” snippet also references container without defining it, so it won’t compile. Define the container from the client before using it.

var client = new CosmosClient(dedicatedGatewayConnectionString);

var options = new ItemRequestOptions

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Bhuvansh (BHUVANSH855)]

hi Sajeetharan (@sajeetharan) Jay Gordon (@jaydestro) Theo van Kraay (@TheovanKraay),

just checking regarding this PR, any updates ?

[Sajeetharan (sajeetharan)]

Please also update the existing sdk-connection-mode.md rule. It currently says Gateway mode is only needed for firewall-restricted environments, but integrated cache is another valid production use case requiring Gateway mode. Without that update, the compiled guidance will conflict. Please also bump the package version using npm run version .

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Suppressed comments (1)

skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md:27

• This sentence references "repeated" requests, but after updating the example label to a single point read, the wording becomes inconsistent. Reword to avoid implying the snippet demonstrates repetition.

Every repeated request is sent to the backend, consuming RUs even when the data has not changed.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

skills/cosmosdb-best-practices/rules/sdk-connection-mode.md:61

• The Gateway-mode exception list mentions Integrated Cache, but this comment doesn’t make it explicit that Integrated Cache requires using the dedicated gateway endpoint/connection string (not just setting ConnectionMode = Gateway). Making that explicit here will prevent readers from assuming Gateway mode alone enables the feature.

    // 4. Using Azure Cosmos DB Integrated Cache, which requires the dedicated gateway