@raishin/vanguard-frontier-agentic 2.7.1 → 2.9.0

package/skills/azure/azure-cosmosdb-application-developer/references/safety-checklist.md

@@ -0,0 +1,32 @@
+# Safety checklist for Azure Cosmos DB Application Developer
+
+## Non-negotiable gates
+
+- Never ask for account keys, connection strings, customer documents, full database dumps, tenant identifiers, subscription identifiers, or private data.
+- Do not recommend a partition key without read/write access-pattern, cardinality, growth, and hot-key analysis.
+- Do not recommend broad cross-partition scans as the normal path for high-volume user flows.
+- Do not present RU cost as fixed without measured request charge and workload context.
+- Require explicit approval before changing indexing policy, partition strategy, TTL, consistency, throughput, SDK retry policy, or data shape in existing workloads.
+
+## High-risk assumptions to kill
+
+- "We can model it like a relational database." Cosmos DB design is query and partition driven.
+- "More RUs will fix the design." It can hide partition or query defects and increase cost.
+- "Transactional batch works across arbitrary documents." It is scoped to operations with the same logical partition key.
+- "Strong consistency is always safer." It can reduce throughput and increase latency; correctness requirements must justify it.
+- "Index everything." Indexing helps queries but increases write RU consumption.
+
+## Evidence labels
+
+- `docs_only`: Microsoft Learn guidance only.
+- `design_review`: user-supplied schema/API/access-pattern design reviewed, not measured.
+- `measured_request`: request charge, query metrics, or diagnostics were provided or sampled.
+- `mutation_ready`: change scope, backfill/migration, rollback, and approval are documented.
+
+## Minimum safe evidence
+
+- API surface, container purpose, entity types, expected document sizes, and growth.
+- Top read and write access patterns with frequency, latency, and consistency requirements.
+- Candidate partition keys with cardinality, distribution, hot-key risk, and transactional grouping needs.
+- Query shapes, point-read opportunities, indexing needs, and expected RU budget.
+- Migration/backfill strategy for existing containers.

package/skills/azure/azure-cosmosdb-application-developer/references/workflow-and-output.md

@@ -1,36 +1,36 @@
-# Workflow and output contract
+# Workflow and output contract for Azure Cosmos DB Application Developer
 
-Use this reference only when you are performing the full review or implementation-guidance pass.
+## Minimal safe workflow
 
-## Workflow
+1. Classify the task: greenfield model, partition-key review, query design, transactional batch, SDK behavior, consistency, or change-feed design.
+2. Ground the answer in Microsoft Learn through the user's configured documentation MCP.
+3. Capture workload evidence: API type, entities, access patterns, data size, consistency needs, RU budget, and growth.
+4. Stress test partition keys: cardinality, distribution, hot keys, transaction grouping, locality, and future access patterns.
+5. Stress test query design: point reads first, partition-scoped queries, projections, index policy, pagination, and diagnostics.
+6. Stress test correctness: consistency level, optimistic concurrency, transactional batch scope, idempotency, and change feed behavior.
+7. Return concrete design guidance with risks, unknowns, and measurement plan.
 
-1. **Scope the target**
-   - Confirm API/workload if known: NoSQL, Mongo, Cassandra, Gremlin, Table, or unknown.
-   - Confirm whether the user needs this role specifically, not an adjacent Azure role.
-   - Confirm whether the question is about an existing workload or a new design.
+## Output contract
 
-2. **Establish evidence level**
-   - Use live Azure MCP evidence when available.
-   - Otherwise use official docs plus sanitized user evidence.
-   - Explicitly label unknowns.
+```markdown
+## Verdict
+<recommended | conditional | not recommended | docs-only advisory>
 
-3. **Stress checks**
-   - Check the target API/workload, dominant read/write patterns, and whether the workload is greenfield or existing.
-   - Stress-test data modeling: embed vs reference, unbounded arrays, precalculated aggregates, and document growth.
-   - Prefer point reads and partition-aware queries; challenge lazy cross-partition scans and RU-blind joins-by-application.
-   - Call out transactional batch scope, session-consistency behavior, and SDK request-charge observability.
+## Evidence level
+- Documentation: <sources used>
+- Workload evidence: <design_review | measured_request | not provided>
 
-4. **Check adjacent roles the user may be missing**
-   - **Azure Cosmos DB Platform Operator** when the real issue is account/platform posture rather than code-facing design.
-   - **Azure Observability Investigator** when the next problem is tracing query latency, alerts, or telemetry gaps.
-   - **Azure AI Foundry Ops Governor** when Cosmos DB becomes part of a larger AI application governance path.
+## Design assessment
+1. <finding> — Evidence: <docs_only|design_review|measured_request|inference>
 
-## Output contract
+## Partition and query decision
+- Partition key: <recommendation or blocker>
+- Access pattern fit: <summary>
+
+## Safe next actions
+- <measurement or design step>
+```
 
-Use this structure:
+## Pushback triggers
 
-1. **Verdict**
-2. **Evidence level**
-3. **Key findings**
-4. **Safest next actions**
-5. **Open questions**
+Push back on vague partition keys, relational normalization by default, fan-out queries on critical paths, unmeasured RU claims, cross-partition transaction assumptions, or consistency choices with no business correctness requirement.

package/skills/azure/azure-cosmosdb-performance-investigator/SKILL.md

@@ -4,8 +4,8 @@ description: Use this skill for Azure Cosmos DB performance investigation, espec
 allowed-tools: Read Grep Glob WebFetch
 metadata:
   author: github: Raishin
-  version: 0.1.0
-  updated: "2026-05-05"
+  version: 0.1.3
+  updated: "2026-06-05"
   category: data
 ---
 
@@ -45,7 +45,7 @@ Do not use this skill as a substitute for:
 
 ## Lean operating rules
 
-- Prefer live Azure or Microsoft evidence first when the active client exposes it; otherwise fall back to official documentation and sanitized user evidence.
+- Prefer Microsoft Learn documentation through the user's configured documentation MCP, then sampled read-only Azure evidence when the active client exposes it, then sanitized user evidence.
 - Separate confirmed facts from inference. If state was not queried or shown, say so.
 - Challenge throughput-first fixes that ignore partition skew, query scans, indexing, or client retry inflation.
 - Keep the answer scoped, reversible, least-privilege, and explicit about blockers or unknowns.
@@ -54,7 +54,9 @@ Do not use this skill as a substitute for:
 
 Load these only when needed:
 
-- [MCP and evidence path](references/mcp-and-evidence.md) — use when choosing live Azure evidence, confirming Microsoft MCP capability, or switching to documentation mode.
+- [Operations guide](references/cosmosdb-performance-investigation.md) — use for service-specific pitfalls, design rules, verification targets, and pushback criteria.
+- [MCP and evidence path](references/mcp-and-evidence.md) — use when choosing documentation-based evidence, sampled read-only Azure evidence, or sanitized user evidence.
+- [Safety checklist](references/safety-checklist.md) — use for evidence labels, risk gates, mutation boundaries, approval rules, and credential boundaries.
 - [Workflow and output contract](references/workflow-and-output.md) — use when executing the full investigation, applying stress checks, or formatting the final answer.
 - [Data profiling playbook](references/data-profiling-playbook.md) — use when you need the detailed step-by-step profiling sequence.
 - [Official sources](references/official-sources.md) — use when you need the detailed Microsoft documentation list or source notes.

package/skills/azure/azure-cosmosdb-performance-investigator/metadata.json

@@ -1,7 +1,7 @@
 {
   "id": "azure-cosmosdb-performance-investigator",
   "name": "Azure Cosmos DB Performance Investigator",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "skill",
   "provider": "azure",
   "harnesses": [
@@ -15,19 +15,19 @@
   "summary": "Investigate Azure Cosmos DB query latency, RU inefficiency, throttling, hot partitions, indexing gaps, and workload-level performance pathologies using explicit evidence, metrics, and step-by-step profiling discipline.",
   "source_type": "original",
   "official_docs": [
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/overview",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/concepts",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-query-performance",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/query-metrics",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/index-metrics",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/use-metrics",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-redistribute-throughput-across-partitions",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips-dotnet-sdk-v3",
-    "https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db"
+    "https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-normalized-request-units",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/autoscale-faq",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/understand-request-unit-consumption"
   ],
   "security_notes": "Do not recommend throughput increases, repartitioning, indexing changes, or SDK tuning before separating RU cost, latency, partition skew, and query-shape evidence. Avoid speculative fixes that hide workload design defects.",
-  "last_verified": "2026-04-28",
+  "last_verified": "2026-06-05",
   "path": "skills/azure/azure-cosmosdb-performance-investigator",
   "author": "github: Raishin"
 }

package/skills/azure/azure-cosmosdb-performance-investigator/references/cosmosdb-performance-investigation.md

@@ -0,0 +1,62 @@
+# Cosmos DB performance investigation
+
+## What people get wrong
+
+- They add RUs before proving whether the problem is global load, hot partitions, query scans, indexing, document size, consistency, or client retries.
+- They look only at average latency and miss p95/p99, 429s, partition-level normalized RU, and retry inflation.
+- They inspect query text without query metrics or request charge.
+- They treat physical partition pressure as proof of a specific logical key before checking diagnostic logs.
+- They change indexing or partition strategy without rollback and backfill planning.
+
+## Officially grounded service shape
+
+Microsoft Learn states that RU consumption depends on document size, indexing, consistency, query shape, and operation type. Each request exposes request charge. Query metrics break down query work, and Azure Monitor/Insights expose Total Request Units, normalized RU by partition key range, throttling, storage, and latency signals. Hot partitions appear when one or a few partition key ranges consume disproportionate RU/s.
+
+## Non-negotiable design rules
+
+1. Establish a time window before collecting metrics.
+2. Separate account/container-level symptoms from operation/query-level symptoms.
+3. Capture request charge and query metrics for representative operations.
+4. Check normalized RU by partition key range before assuming global under-provisioning.
+5. Check status codes and retry behavior before blaming service latency.
+6. Treat indexing changes, throughput changes, and data reshaping as mutations requiring approval.
+7. Prefer reversible experiments before structural changes.
+
+## Minimal safe implementation flow
+
+1. Define symptom, workload path, API type, region, and time window.
+2. Collect aggregate metrics: total RU, 429s, latency percentiles, operation type, status code, and region.
+3. Collect partition metrics: normalized RU by partition key range and top logical partition evidence when diagnostics are available.
+4. Profile representative operations: request charge, query metrics, index metrics, result count, page count, and continuation behavior.
+5. Profile client: SDK version, connection mode, retries, timeouts, diagnostics, and deployment region path.
+6. Rank root causes and propose one low-risk experiment per suspected cause.
+7. Document approval and rollback before changing throughput, index policy, partitioning, consistency, or SDK retry behavior.
+
+## High-risk assumptions to kill
+
+- More RU/s is not a root-cause fix when one partition key range is hot, a query scans, indexing is wrong, or clients are retrying badly.
+- Average latency hides tail latency, retries, page count, continuation behavior, regional routing, and partition-level pressure.
+- A physical partition hot spot does not identify the logical offender until diagnostic logs or equivalent partition-key evidence is available.
+- Index metrics are troubleshooting evidence, not a reason to enable expensive diagnostics or change indexing permanently without rollback.
+- Autoscale reaching 100% normalized RU briefly is not automatically unhealthy; rate of 429s and end-to-end latency decide urgency.
+
+## Safe command/code verification targets
+
+- Inspect application code for request-charge logging, SDK diagnostics capture, retry configuration, connection mode, timeout settings, and preferred region behavior.
+- Check query code and captured metrics for retrieved-versus-output document counts, index hit ratio, page count, continuation-token handling, and cross-partition execution.
+- Review Azure Monitor/Kusto queries or dashboards for normalized RU by partition key range, 429 percentage, operation type, p95/p99 latency, and regional splits.
+- Verify index-policy changes are represented as reviewed diffs with before/after RU and latency measurements plus rollback steps.
+- Confirm throughput, consistency, partition-key, or SDK tuning recommendations include an experiment boundary and post-change measurement window.
+
+## Safe verification targets
+
+- `RequestCharge` per representative read, write, and query.
+- Query metrics: index lookup, document load, output document count, retrieved document count, and execution time components.
+- Index metrics for filter and sort support.
+- Normalized RU consumption split by partition key range.
+- 429 count, retry count, p95/p99 latency, and region routing.
+- Before/after measurement for each remediation experiment.
+
+## When to push back
+
+Push back when the proposed fix is "increase RUs" without partition/query proof, repartitioning without distribution evidence, index changes without query metrics, or SDK changes without diagnostics.

package/skills/azure/azure-cosmosdb-performance-investigator/references/mcp-and-evidence.md

@@ -1,38 +1,27 @@
-# MCP and evidence path
+# MCP and evidence path for Cosmos DB performance investigation
 
-Use this reference only when you need to decide how to gather Cosmos DB performance evidence.
+Use Microsoft Learn documentation through the user's configured documentation MCP as the first grounding path for Azure service behavior. This file defines evidence boundaries; it must not imply that documentation proves the user's tenant, subscription, RBAC, quotas, deployed resources, or production readiness.
 
-## Live-first evidence rule
+## Evidence ladder
 
-1. Prefer live Azure MCP capability evidence when the active client exposes Azure tools.
-2. Treat the runtime-exposed tool inventory as truth.
-3. If Cosmos DB tooling is not exposed live, say so and switch to documentation-based guidance instead of pretending the namespace exists.
+1. `docs_only`: Microsoft Learn documentation and official architecture guidance. Use for documented behavior, caveats, and safe review criteria.
+2. `sampled_read_only`: configured-environment evidence from read-only tools, if available and explicitly scoped. Use only for the sampled resource/time window.
+3. `user_supplied`: sanitized outputs, IaC, diagrams, or metrics provided by the user. Treat as unverified unless independently checked.
+4. `mutation_ready`: documentation plus current-state evidence plus explicit approval, blast-radius statement, and rollback path.
 
-## Azure MCP grounding
+## Rules
 
-Based on Microsoft documentation:
+- Do not expose environment-specific implementation details in committed docs or user-facing guidance.
+- Do not ask for credentials, tokens, tenant identifiers, subscription identifiers, connection strings, private keys, customer data, or raw secrets.
+- If current-state evidence was not sampled, say `not sampled`; do not imply it.
+- If evidence is representative or partial, say so. A sample does not prove broad regional availability or production readiness.
+- Prefer read-only evidence before mutation planning. Stop for approval before write operations.
 
-- Azure MCP supports a documented `cosmos` namespace in namespace mode.
-- Microsoft recommends **consolidated mode** for AI agents because it reduces tool count and improves usability.
-- Namespace filtering means a client may expose only a subset of Azure tools.
+## Final-answer evidence language
 
-Implication:
+Use phrases like:
 
-- Do not assume that `cosmos` is available in the current runtime just because Microsoft documents it.
-- If live MCP discovery is unclear, inspect or ask for the available Azure tool inventory before making namespace-specific claims.
-
-## Evidence hierarchy
-
-Use this order:
-
-1. **live evidence** — Azure MCP output, sanitized metrics, sanitized Data Explorer screenshots, sanitized query metrics, or diagnostic-log output
-2. **user-provided sanitized evidence** — redacted SDK traces, query text, request-charge samples, portal screenshots, IaC snippets, logs
-3. **documentation-based** — Microsoft Learn and official Azure MCP documentation
-4. **inference** — conclusions derived from patterns but not directly proven by evidence
-
-## Performance-specific caution points
-
-- A 429 spike does not automatically prove underprovisioning; it can also indicate skew, bursts, or bad query shape.
-- Acceptable RU charge does not prove acceptable latency.
-- High latency does not automatically prove server-side slowness; region distance, retries, and client configuration matter.
-- Index metrics are for troubleshooting; do not turn them into always-on ritual without cause.
+- "Based on Microsoft Learn documentation..."
+- "Configured-environment evidence was not sampled in this review."
+- "The following is an inference from the provided configuration, not proven live state."
+- "This recommendation is mutation-ready only after explicit approval and rollback review."

package/skills/azure/azure-cosmosdb-performance-investigator/references/official-sources.md

@@ -1,37 +1,24 @@
-# Official sources
+# Official sources for Azure Cosmos DB Performance Investigator
 
-Use this reference only when you need the detailed source list or need to ground a specific claim.
+Use Microsoft Learn documentation through the user's configured documentation MCP before recommending performance fixes. Documentation proves service behavior; it does not prove this user's hot partitions, RU budget, indexes, SDK behavior, retry inflation, or latency root cause.
 
-## Azure MCP
+## Primary Microsoft Learn sources
 
-- Azure MCP overview
-  https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/overview
-- Azure MCP concepts
-  https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/concepts
-- Azure MCP tools overview
-  https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/
+| Source | Review implication |
+| --- | --- |
+| [Troubleshoot query performance](https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-query-performance) | Use for slow query triage, query metrics, index utilization, and query-shape remediation. |
+| [Query metrics](https://learn.microsoft.com/en-us/azure/cosmos-db/query-metrics) | Require query metrics before claiming where query time or RU cost is going. |
+| [Index metrics](https://learn.microsoft.com/en-us/azure/cosmos-db/index-metrics) | Use to validate whether current indexes support filters and sorts. |
+| [Understand request units consumption](https://learn.microsoft.com/en-us/azure/cosmos-db/understand-request-unit-consumption) | Ground RU cost in document size, indexing, consistency, and query shape. |
+| [Monitor and debug with insights](https://learn.microsoft.com/en-us/azure/cosmos-db/use-metrics) | Use for throughput, storage, normalized RU, request charge, and partition-key-range views. |
+| [Monitor normalized request units](https://learn.microsoft.com/en-us/azure/cosmos-db/monitor-normalized-request-units) | Use to detect physical partition pressure and hot partition indicators. |
+| [Diagnose and troubleshoot request rate too large](https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-request-rate-too-large) | Use for 429 and throttling diagnostics, including hot partition analysis. |
+| [Redistribute throughput across partitions](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-redistribute-throughput-across-partitions) | Treat as preview/limited remediation for eligible accounts; verify limitations before suggesting. |
+| [Performance tips for .NET SDK v3](https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips-dotnet-sdk-v3) | Use for SDK-side diagnostics, retry, connection, and request-charge instrumentation patterns when .NET is in scope. |
 
-## Azure Cosmos DB performance and profiling
+## Source-grounding rules
 
-- Troubleshoot query issues when using Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/troubleshoot-query-performance
-- Tuning query performance with Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/query-metrics
-- Indexing metrics in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/index-metrics
-- Monitor and debug with insights in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/use-metrics
-- Redistribute throughput across partitions in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-redistribute-throughput-across-partitions
-- Performance tips for Azure Cosmos DB and .NET
-  https://learn.microsoft.com/en-us/azure/cosmos-db/performance-tips-dotnet-sdk-v3
-- Partitioning and horizontal scaling in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning
-- Architecture best practices for Azure Cosmos DB for NoSQL
-  https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db
-
-## Grounded insights used by this skill
-
-- Request charge, query metrics, and partition-level metrics are more trustworthy than intuition.
-- High RU and high latency are not the same failure mode.
-- Hot-partition diagnosis needs partition-range and logical-key evidence, not just aggregate throttling counts.
+- Never recommend "add RUs" before separating hot partition, inefficient query, indexing, consistency, document size, and client retry causes.
+- Query metrics and request charge are stronger evidence than aggregate charts for a single query path.
+- Normalized RU by partition key range is a hot-partition signal, not proof of the exact logical key unless diagnostics identify it.
+- Throughput redistribution has eligibility and preview caveats; do not present it as a default fix.

package/skills/azure/azure-cosmosdb-performance-investigator/references/safety-checklist.md

@@ -0,0 +1,32 @@
+# Safety checklist for Azure Cosmos DB Performance Investigator
+
+## Non-negotiable gates
+
+- Never ask for account keys, connection strings, full documents, customer data, tenant identifiers, subscription identifiers, or database dumps.
+- Do not recommend throughput changes, indexing changes, repartitioning, SDK retry changes, consistency changes, or data reshaping without evidence and rollback.
+- Treat diagnostic logs as potentially sensitive. Ask only for sanitized aggregates, query text with literals removed, or metrics screenshots summarized in text.
+- Do not claim root cause from a single metric. Correlate RU, latency, status codes, partition distribution, query metrics, and client retries.
+- Require explicit approval before any write or configuration mutation.
+
+## High-risk assumptions to kill
+
+- "429 means under-provisioned globally." It may be a hot partition or retry pattern.
+- "High latency means service issue." It may be query fan-out, index miss, large documents, consistency, region path, or client connection mode.
+- "Normalized RU at 100% always equals failures." It can spike without broad 429s; correlate with status and workload.
+- "Indexing more properties improves performance." It can increase write cost and may not fix query shape.
+- "Throughput redistribution fixes a bad partition key." It may reduce symptoms but not remove skewed design risk.
+
+## Evidence labels
+
+- `docs_only`: Microsoft Learn guidance only.
+- `metrics_sample`: sanitized Azure Monitor or Insights metrics reviewed.
+- `query_profile`: request charge, query metrics, index metrics, diagnostics, or SDK logs reviewed.
+- `remediation_ready`: proposed change has measured baseline, blast radius, rollback, and approval.
+
+## Minimum safe evidence
+
+- Time window, region, API type, account/container, workload path, and symptom.
+- Total Request Units, 429 counts, normalized RU by partition key range, latency percentiles, and operation type.
+- Representative query text with sensitive literals removed, request charge, query metrics, index metrics, and result counts.
+- SDK version, connection mode, retry policy, timeout behavior, and diagnostics for client-perceived latency.
+- Recent changes in traffic, data volume, indexing, regions, consistency, or deployments.

package/skills/azure/azure-cosmosdb-performance-investigator/references/workflow-and-output.md

@@ -1,46 +1,38 @@
-# Workflow and output contract
-
-Use this reference only when you are performing the full performance investigation.
-
-## Workflow
-
-1. **Scope the target**
-   - Confirm API/workload if known: NoSQL, Mongo, Cassandra, Gremlin, Table, or unknown.
-   - Confirm whether the symptom is RU cost, latency, throttling, partition skew, or mixed.
-   - Confirm whether the issue is one query, one container, one service, or a broader workload.
-
-2. **Establish evidence level**
-   - Use live Azure MCP evidence when available.
-   - Otherwise use official docs plus sanitized user evidence.
-   - Explicitly label unknowns.
-
-3. **Separate the failure modes before prescribing fixes**
-   - RU inefficiency
-   - latency despite acceptable RU
-   - 429 throttling and retry amplification
-   - hot partition / physical partition skew
-   - indexing mismatch or query scan behavior
-   - client-side concurrency / buffering / proximity issues
-
-4. **Prefer measurement over guesswork**
-   - request charge
-   - query metrics
-   - index metrics when troubleshooting
-   - normalized RU consumption by partition key range
-   - diagnostic logs for partition-level RU consumers
-
-5. **Check adjacent roles the user may be missing**
-   - **Azure Cosmos DB Platform Operator** when the root issue becomes throughput posture, account-level configuration, or broader platform controls.
-   - **Azure Cosmos DB Application Developer** when the dominant defect is data model, access pattern, or code-side query design.
-   - **Azure Observability Investigator** when the next problem is telemetry pipeline, alerts, or broader operational visibility.
-   - **Azure Cost Optimization Governor** when the recurring question becomes budget, autoscale governance, or cost-control posture.
+# Workflow and output contract for Azure Cosmos DB Performance Investigator
+
+## Minimal safe workflow
+
+1. Classify symptom: high RU, latency, 429, hot partition, index miss, SDK/client issue, or mixed.
+2. Ground the investigation with Microsoft Learn through the user's configured documentation MCP.
+3. Establish time window and scope without exposing sensitive identifiers.
+4. Build a four-lane evidence table: service metrics, query profile, partition profile, and client profile.
+5. Rank likely causes only after correlating request charge, query metrics, normalized RU, status codes, latency, and retries.
+6. Propose lowest-risk experiments before irreversible changes.
+7. Require approval and rollback for any throughput, index, data model, partition, consistency, or SDK policy mutation.
 
 ## Output contract
 
-Use this structure:
+```markdown
+## Verdict
+<root cause likely | mixed causes | insufficient evidence | docs-only advisory>
+
+## Evidence level
+- Documentation: <sources used>
+- Metrics/query evidence: <metrics_sample | query_profile | not provided>
+
+## Findings
+1. <finding> — Evidence: <docs_only|metrics_sample|query_profile|inference>
+
+## Root-cause ranking
+1. <cause> — why it is likely / what would disprove it
+
+## Safe next profiling steps
+- <specific metric/query/diagnostic to collect>
+
+## Remediation boundaries
+- <changes that require approval and rollback>
+```
+
+## Pushback triggers
 
-1. **Verdict**
-2. **Evidence level**
-3. **Key findings**
-4. **Safest next actions**
-5. **Open questions**
+Push back on blind RU increases, unmeasured index changes, repartitioning without hot-key proof, query rewrites without query metrics, or SDK tuning without client diagnostics.

package/skills/azure/azure-cosmosdb-platform-operator/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: azure-cosmosdb-platform-operator
-description: Use this skill for Azure Cosmos DB platform operations and design review, especially accounts, databases, containers, partition-key design, throughput and RU posture, consistency choices, indexing, throttling, multi-region replication, private connectivity, and Cosmos DB MCP-guided discovery.
+description: Use this skill for Azure Cosmos DB platform operations and design review, especially accounts, databases, containers, partition-key design, throughput and RU posture, consistency choices, indexing, throttling, multi-region replication, private connectivity, and Cosmos DB evidence-guided discovery.
 allowed-tools: Read Grep Glob
 metadata:
   author: github: Raishin
-  version: 0.1.0
-  updated: "2026-05-05"
+  version: 0.1.3
+  updated: "2026-06-05"
   category: platform
 ---
 
@@ -23,7 +23,7 @@ Use this skill when the user asks for:
 - partition-key, consistency, throughput, or indexing decisions,
 - RU cost, throttling, hot partition, or multi-region tradeoff analysis,
 - private endpoint, failover, or platform control-plane posture questions,
-- Cosmos DB MCP-backed discovery or evidence gathering.
+- Cosmos DB documentation-grounded discovery or sampled read-only evidence gathering.
 
 Do not use this skill as a substitute for:
 
@@ -34,7 +34,7 @@ Do not use this skill as a substitute for:
 
 ## Lean operating rules
 
-- Prefer live Azure or Microsoft evidence first when the active client exposes it; otherwise fall back to official documentation and sanitized user evidence.
+- Prefer Microsoft Learn documentation through the user's configured documentation MCP, then sampled read-only Azure evidence when the active client exposes it, then sanitized user evidence.
 - Separate confirmed facts from inference. If state was not queried or shown, say so.
 - Challenge broad scope, vague partition keys, and RU-blind advice.
 - Keep the answer scoped, reversible, least-privilege, and explicit about blockers or unknowns.
@@ -43,7 +43,9 @@ Do not use this skill as a substitute for:
 
 Load these only when needed:
 
-- [MCP and evidence path](references/mcp-and-evidence.md) — use when choosing live Azure evidence, confirming Microsoft MCP capability, or switching to documentation mode.
+- [Operations guide](references/cosmosdb-platform-operations.md) — use for service-specific pitfalls, design rules, verification targets, and pushback criteria.
+- [MCP and evidence path](references/mcp-and-evidence.md) — use when choosing documentation-based evidence, sampled read-only Azure evidence, or sanitized user evidence.
+- [Safety checklist](references/safety-checklist.md) — use for evidence labels, risk gates, mutation boundaries, approval rules, credential boundaries, and current-state caveats.
 - [Workflow and output contract](references/workflow-and-output.md) — use when executing the full review, applying stress checks, or formatting the final answer.
 - [Official sources](references/official-sources.md) — use when you need the detailed Microsoft documentation list or source notes.
 

package/skills/azure/azure-cosmosdb-platform-operator/metadata.json

@@ -1,7 +1,7 @@
 {
   "id": "azure-cosmosdb-platform-operator",
   "name": "Azure Cosmos DB Platform Operator",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "skill",
   "provider": "azure",
   "harnesses": [
@@ -15,19 +15,19 @@
   "summary": "Review and operate Azure Cosmos DB platform posture across accounts, databases, containers, partitioning, throughput, consistency, indexing, throttling, multi-region tradeoffs, and operational guardrails with explicit evidence-versus-inference handling.",
   "source_type": "original",
   "official_docs": [
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/overview",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/concepts",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/modeling-data",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-consistency",
     "https://learn.microsoft.com/en-us/azure/cosmos-db/query-metrics",
     "https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db",
-    "https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys"
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys",
+    "https://learn.microsoft.com/en-us/azure/reliability/reliability-cosmos-db",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys-unlimited-scale",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/failover-considerations-for-private-endpoints"
   ],
   "security_notes": "Do not approve a partition key, indexing posture, consistency change, or cross-partition query strategy without checking workload shape, RU impact, transactional scope, and least-privilege access implications.",
-  "last_verified": "2026-04-28",
+  "last_verified": "2026-06-05",
   "path": "skills/azure/azure-cosmosdb-platform-operator",
   "author": "github: Raishin"
 }

package/skills/azure/azure-cosmosdb-platform-operator/references/cosmosdb-platform-operations.md

@@ -0,0 +1,62 @@
+# Cosmos DB platform operations
+
+## What people get wrong
+
+- They treat account-level multi-region settings as proof the application fails over safely.
+- They ignore SDK preferred-region configuration, private DNS, and remaining-region throughput when reviewing regional resiliency.
+- They change consistency, failover priority, or throughput during stress without knowing the blast radius.
+- They view backup as an availability feature instead of a data-recovery feature.
+- They approve partitioning from a diagram instead of measured access patterns and distribution.
+
+## Officially grounded service shape
+
+Microsoft Learn describes Cosmos DB as an account containing databases and containers, with containers as logical units of distribution and scalability. Reliability features include zone redundancy, multi-region replication, several consistency levels, service-managed or customer-managed failover, SDK resiliency behavior, and continuous or periodic backup. The reliability guide also warns against control-plane changes on affected regions during outage scenarios and calls out private endpoint DNS considerations after failover.
+
+## Non-negotiable design rules
+
+1. Identify API type, write model, regions, consistency, backup, and throughput mode before giving a platform verdict.
+2. Treat partitioning and throughput as workload-coupled, not platform-only decisions.
+3. Verify SDK region preference and retry behavior for multi-region availability.
+4. For private endpoints, design regional endpoints and DNS resolution deliberately.
+5. Size remaining regions for failover load before claiming regional resilience.
+6. Use backup/restore for data corruption/deletion scenarios; use multi-region and failover for availability scenarios.
+7. Require diagnostics, Resource Health, Service Health, alerts, and DR runbooks.
+
+## Minimal safe implementation flow
+
+1. Inventory account topology: API, regions, write model, consistency, backup, throughput, network access, and private endpoints.
+2. Review workload shape: partition key, hot partition risk, RU headroom, critical operations, and consistency needs.
+3. Review reliability: zone redundancy, failover mode, preferred regions, capacity under region loss, and DR drills.
+4. Review network: private endpoints, DNS zones, hub/spoke forwarding, firewall, and client routing.
+5. Review operations: metrics, logs, alerts, backup restore testing, and owner/runbook evidence.
+6. Rank blockers and reversible remediations.
+7. Require explicit approval before any control-plane mutation.
+
+## High-risk assumptions to kill
+
+- Multi-region account configuration does not prove application failover unless SDK preferred regions, retries, conflict handling, and remaining-region capacity are verified.
+- Private endpoints can break regional resilience if DNS zones, VNet links, forwarding, and local regional endpoint paths are not designed deliberately.
+- Strong, bounded staleness, session, and eventual consistency have different availability, RPO, and throughput implications; do not treat consistency as a cosmetic setting.
+- Control-plane changes during an affected-region outage can delay recovery; do not mutate write region, consistency, throughput, networking, or failover priorities casually.
+- Backup protects data recovery scenarios; it is not a substitute for live availability, failover routing, or tested application DR.
+
+## Safe command/code verification targets
+
+- Inspect IaC for account regions, zone redundancy, failover priorities, write-region model, consistency, backup mode, throughput mode, and private endpoint resources.
+- Review application configuration for SDK preferred regions, excluded regions, retry diagnostics, conflict resolution, and multi-write support where applicable.
+- Check network templates for one-region-per-DNS-zone patterns, private DNS links, forwarding rules, firewall dependencies, and client resolution paths.
+- Verify monitoring code or dashboards cover normalized RU, 429s, region availability, Resource Health, Service Health, backup status, and restore-test evidence.
+- Confirm every proposed account mutation has an approval gate, rollback plan, and explicit outage-state caveat.
+
+## Safe verification targets
+
+- Account regions, write region or multi-write state, failover priorities, and service-managed/forced failover process.
+- Consistency level and documented RPO/availability implications.
+- Throughput mode and normalized RU headroom by partition key range.
+- Private endpoint count, DNS zones, VNet links, forwarding, and client resolution path.
+- Backup mode, retention, restore test, and data-corruption response plan.
+- SDK preferred regions, retry, partition-level circuit breaker or equivalent availability settings.
+
+## When to push back
+
+Push back on production signoff without failover evidence, private endpoint DNS proof, capacity-under-failure math, SDK routing proof, backup restore tests, or partition distribution evidence.