@raishin/vanguard-frontier-agentic 2.8.0 → 2.9.0

package/skills/azure/azure-app-service-production-readiness/references/safety-checklist.md

@@ -0,0 +1,33 @@
+# Safety checklist for Azure App Service Production Readiness
+
+## Non-negotiable gates
+
+- Never ask for publish profiles, connection strings, certificates, private keys, app secrets, tenant identifiers, subscription identifiers, or customer data.
+- Do not approve production if rollback, health checks, diagnostics, managed identity, secret flow, networking, and owner/runbook evidence are missing.
+- Treat app settings as sensitive. Do not echo values; reason about names and references only.
+- Require explicit approval before app setting changes, slot swaps, scale changes, network changes, identity changes, backup changes, or restart operations.
+- Do not equate App Service managed platform with workload resilience. Application dependencies and state stores remain the user's responsibility.
+
+## High-risk assumptions to kill
+
+- "Premium plan means production-ready." SKU is one input, not evidence of readiness.
+- "Slots make deployment safe." Slot settings, warm-up, health, dependency compatibility, and rollback must be proven.
+- "Private endpoint means no public exposure." Public access, access restrictions, DNS, reverse proxy, and SCM endpoint behavior still need review.
+- "App Service backup covers the database." Linked database backup support has deprecation caveats; use native database backup/restore for state stores.
+- "Key Vault references remove all secret risk." Managed identity permissions, network routing, slot settings, and reference resolution must be checked.
+
+## Evidence labels
+
+- `docs_only`: Microsoft Learn guidance only.
+- `sampled_read_only`: current app or plan evidence was sampled safely.
+- `config_review`: IaC/app configuration was reviewed but not proven live.
+- `restore_proven`: backup/restore or rollback was tested and evidence exists.
+- `mutation_ready`: blast radius, rollback, and explicit approval exist.
+
+## Minimum safe evidence
+
+- App Service plan tier, instance count, OS, region, zone posture, and scale rules.
+- Deployment slot count, swap strategy, sticky settings, warm-up path, and rollback path.
+- Ingress model, public access/access restrictions, private endpoint, DNS, WAF/reverse proxy, and SCM restrictions.
+- VNet integration, outbound routing, private dependencies, Key Vault references, and managed identity permissions.
+- Health check, diagnostics, alerts, dashboards, backup/restore tests, and on-call ownership.

package/skills/azure/azure-app-service-production-readiness/references/workflow-and-output.md

@@ -1,125 +1,38 @@
-# Workflow and Output Contract
+# Workflow and output contract for Azure App Service Production Readiness
 
-## Safe Workflow
+## Minimal safe workflow
 
-1. **Classify the workload and blast radius**
-   - What is the app?
-   - Who uses it?
-   - What breaks if it fails?
-   - What are the RTO/RPO and maintenance-window assumptions?
-2. **Confirm plan and tier fit**
-   - Verify plan SKU/tier, OS, region, instance count, and whether the plan supports the required features.
-   - Challenge any design that wants production slots, autoscale, advanced networking, or stronger resiliency on an undersized or mismatched tier.
-3. **Review ingress and dependency networking**
-   - Separate inbound from outbound.
-   - Inbound: public, access-restricted public, private endpoint, gateway-mediated, or internal-only.
-   - Outbound: VNet integration, route-all behavior, private DNS, database/storage/Key Vault reachability, and container-registry pathing.
-   - Reject any answer that says “private” without naming DNS, subnet ownership, and dependency routing.
-4. **Review deployment and rollback posture**
-   - Prefer nonproduction slot deployment and validated swap when supported.
-   - Challenge direct-to-production deployment.
-   - Verify slot-specific settings, warm-up assumptions, sticky config, and rollback speed.
-5. **Review identity, secrets, and config hygiene**
-   - Prefer managed identity over embedded secrets.
-   - Use Key Vault references when secret separation is required.
-   - Verify slot settings for environment-specific values.
-   - Reject secrets in repo, pipeline variables, copied app settings, or chat.
-6. **Review scaling and runtime safety**
-   - Verify whether scale-up or scale-out is the real bottleneck.
-   - Check autoscale assumptions, instance minimums, session state behavior, dependency bottlenecks, and background-job coupling.
-   - Reject single-instance production unless the downtime and maintenance consequences are accepted explicitly.
-7. **Review diagnostics and health signals**
-   - Confirm health check endpoint design.
-   - Confirm logs, metrics, alerting, and diagnostic ownership.
-   - Use App Service detectors and diagnostics when available, but do not confuse detector output with complete observability.
-8. **Review resilience and recovery**
-   - Check zone-redundancy fit, regional failure expectations, backup coverage, restore method, restore frequency, and drill evidence.
-   - Distinguish backup existence from restore readiness.
-9. **Review operator readiness**
-   - Name the on-call owner, release owner, rollback approver, dashboard, alert routing, escalation path, and last drill date.
-   - If no one owns the failure path, it is not production-ready.
-10. **Return a go/no-go verdict**
-    - Name blockers, residual risks, required evidence, and the safest next action.
+1. Classify workload: public web app, internal app, API, custom container, WebJob, or mixed.
+2. Ground the review with Microsoft Learn through the user's configured documentation MCP.
+3. Define current evidence: docs only, read-only current-state sample, IaC/config review, or user-supplied sanitized evidence.
+4. Review reliability: instances, zones, health check, auto-heal, scaling, statelessness, dependencies, backup, and recovery.
+5. Review security: managed identity, Key Vault references, HTTPS/TLS, public access, private endpoint, access restrictions, SCM, CORS, logs, and secret handling.
+6. Review operations: slots, warm-up, swap, rollback, diagnostics, alerts, release flow, ownership, and drills.
+7. Deliver verdict and blockers. Do not soften no-go findings.
 
-## Role-Specific Stress Checks
-
-- Reject “Premium is production-ready by default.” SKU alone is not readiness.
-- Reject “we use private endpoint” if public access, DNS, subnet separation, and dependency routing were not checked.
-- Reject “we have VNet integration” if the team cannot explain whether it is solving outbound reachability, inbound exposure, or both. Those are different problems.
-- Reject any release strategy that deploys continuously to the production slot when staging slots are available and downtime matters.
-- Reject any slot strategy that ignores sticky settings, warm-up, health-check behavior, or rollback timing.
-- Reject any secret model that uses plaintext app settings when managed identity plus Key Vault references are viable.
-- Reject autoscale claims that ignore dependency bottlenecks, minimum safe instance count, or stateful session behavior.
-- Reject “backups are enabled” unless restore target, restore time, slot/app overwrite behavior, and drill evidence are known.
-- Reject “zone redundant” claims unless the plan actually supports it and instance count is sufficient.
-- Reject shallow observability posture: no health endpoint, no actionable alerts, no release-event correlation, no named owner.
-- Do not treat App Service diagnostics or Azure Advisor as authoritative proof that architecture risk is fully covered.
-
-## Output Template
+## Output contract
 
 ```markdown
-# Azure App Service Production Readiness Review: <scope>
-
 ## Verdict
-- Status: READY / READY WITH RISKS / NOT READY
-- Biggest risk:
-- Evidence level: live evidence / documentation-based / sanitized evidence / inference
+<go | conditional-go | no-go | docs-only advisory>
 
-## Scope
-- Subscription or boundary:
-- Resource group:
-- App Service plan:
-- Web app(s):
-- Environment:
-- Requested decision:
-
-## Workload assumptions
-- Traffic pattern:
-- Availability target:
-- RTO / RPO:
-- Stateful dependencies:
-- Release frequency:
+## Evidence level
+- Documentation: <sources used>
+- Runtime/config evidence: <sampled_read_only | config_review | not sampled>
 
 ## Findings
-| Area | Finding | Severity | Evidence | Why it matters | Recommendation | Owner |
-|---|---|---|---|---|---|---|
+1. <finding> — Evidence: <docs_only|sampled_read_only|config_review|inference>
 
-## Production controls review
-| Control area | Expected state | Observed state | Gap | Blocking |
-|---|---|---|---|---|
-| Plan tier fit |  |  |  |  |
-| Deployment slots and rollback |  |  |  |  |
-| Ingress and private access |  |  |  |  |
-| Outbound dependency reachability |  |  |  |  |
-| Identity and secrets |  |  |  |  |
-| Scale and capacity |  |  |  |  |
-| Diagnostics and alerts |  |  |  |  |
-| Backup and restore |  |  |  |  |
-| Operator readiness |  |  |  |  |
+## Production blockers
+- <blocker>
 
 ## Safe next actions
-1.
-2.
-3.
-
-## Rollback / recovery posture
-1.
-2.
-3.
+- <least-risk action>
 
 ## Open questions
--
+- <question needed for readiness>
 ```
 
-## Red Flags
+## Pushback triggers
 
-- The team wants a production verdict but cannot name the App Service plan SKU, instance count, or dependency network path.
-- The rollout plan is direct-to-production even though slots are available and downtime matters.
-- Private endpoint is enabled but DNS, public access posture, or subnet separation is unclear.
-- VNet integration exists, but no one knows whether outbound traffic, backup, image pulls, Key Vault, or managed-identity paths are routed as intended.
-- Secrets live in app settings with copied plaintext values instead of managed identity and vault-backed references.
-- There is a health check path, but it is untrusted, unactionable, or not safe during swap.
-- Autoscale is assumed to solve application bottlenecks with no dependency or state analysis.
-- Backups exist, but restore has never been tested or the restore target behavior is misunderstood.
-- Alerts fire, but nobody owns them.
-- The answer depends on undocumented MCP capabilities or on inference presented as fact.
+Push back on direct-to-production deployments, no slot rollback, no health endpoint, public access with no threat model, secrets in app settings, no restore test, no alerts, or no named operational owner.

package/skills/azure/azure-cosmosdb-application-developer/SKILL.md

@@ -4,8 +4,8 @@ description: Use this skill for Azure Cosmos DB application development work, es
 allowed-tools: Read Edit Write MultiEdit Grep Glob Bash
 metadata:
   author: github: Raishin
-  version: 0.1.0
-  updated: "2026-05-05"
+  version: 0.1.3
+  updated: "2026-06-05"
   category: data
 ---
 
@@ -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-application-design.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 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-application-developer/metadata.json

@@ -1,7 +1,7 @@
 {
   "id": "azure-cosmosdb-application-developer",
   "name": "Azure Cosmos DB Application Developer",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "type": "skill",
   "provider": "azure",
   "harnesses": [
@@ -15,9 +15,6 @@
   "summary": "Guide Azure Cosmos DB application development across NoSQL data modeling, partition-aware access patterns, point reads, query shape, SDK usage, transactional batch scope, and consistency-aware application behavior 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",
@@ -25,10 +22,13 @@
     "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/transactional-batch",
-    "https://learn.microsoft.com/en-us/azure/cosmos-db/find-request-unit-charge"
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/find-request-unit-charge",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/optimize-cost-reads-writes",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/request-units",
+    "https://learn.microsoft.com/en-us/azure/cosmos-db/understand-request-unit-consumption"
   ],
   "security_notes": "Do not recommend data models, query patterns, transactional assumptions, or SDK usage that ignore partition scope, RU cost, consistency semantics, or least-privilege access boundaries.",
-  "last_verified": "2026-04-28",
+  "last_verified": "2026-06-05",
   "path": "skills/azure/azure-cosmosdb-application-developer",
   "author": "github: Raishin"
 }

package/skills/azure/azure-cosmosdb-application-developer/references/cosmosdb-application-design.md

@@ -0,0 +1,61 @@
+# Cosmos DB application design
+
+## What people get wrong
+
+- They start with entity diagrams instead of access patterns. Cosmos DB data modeling starts from how the application reads and writes.
+- They choose a human-friendly partition key that creates hot logical partitions.
+- They query where they could point-read by ID and partition key.
+- They over-index every property and then wonder why writes are expensive.
+- They assume transactional batch crosses partition keys. It does not.
+
+## Officially grounded service shape
+
+Microsoft Learn explains that RUs are a normalized measure affected by document size, indexing, consistency, query shape, and operations. Point reads using item ID plus partition key are the most efficient reads. Transactional batch provides ACID semantics for operations sharing the same logical partition key. In multi-region accounts, throughput is provisioned in each region and consistency choices affect read throughput.
+
+## Non-negotiable design rules
+
+1. Design containers around dominant access patterns, not just entity type.
+2. Choose partition keys with high cardinality, even request distribution, growth headroom, and locality for transactions or common queries.
+3. Prefer point reads for hot paths. If a query is required, keep it partition-scoped where possible.
+4. Treat document size and indexed properties as write-cost drivers.
+5. State consistency requirements explicitly for each user flow.
+6. Use transactional batch only when all operations share a logical partition key and fit documented limits.
+7. Measure request charge and query metrics before asserting cost or performance.
+
+## Minimal safe implementation flow
+
+1. List top user flows and background jobs with expected read/write frequency.
+2. Define documents, IDs, partition keys, and denormalization based on those flows.
+3. Map each critical read to point read, partition-scoped query, or cross-partition query.
+4. Define indexing policy from actual filters, sort orders, and projections.
+5. Decide consistency per flow, not globally by habit.
+6. Validate with sample data, realistic distribution, request charge logging, query metrics, and failure tests.
+7. Document migration and rollback for existing containers.
+
+## High-risk assumptions to kill
+
+- A partition key that looks logical to humans is unsafe until cardinality, storage growth, and request distribution are tested against real access patterns.
+- Querying by ID plus partition-key equality is not the same as a point read; hot paths should use SDK point-read APIs where possible.
+- Cross-partition queries can be acceptable for low-volume paths, but they are not free and must carry measured RU and latency evidence.
+- Transactional batch is not a cross-partition transaction; every operation must share the same logical partition key.
+- Stronger consistency can change read cost and throughput behavior, so consistency must be selected per user flow, not by default habit.
+
+## Safe command/code verification targets
+
+- Review repository code for point reads that pass both item ID and partition key on hot paths.
+- Check query builders for partition-key filters, continuation-token handling, max item count, and diagnostics or request-charge logging.
+- Inspect container/IaC definitions for partition key path, throughput mode, indexing policy, unique keys, TTL, and analytical/change-feed assumptions.
+- Verify transactional batch code constructs one batch per logical partition key and fails closed when mixed keys appear.
+- Require load-test or fixture evidence that reports request charge, output count, retrieved count, latency, and retry behavior for representative flows.
+
+## Safe verification targets
+
+- Candidate partition-key distribution and top hot-key risks.
+- Request charge for representative create, replace, patch, delete, point read, and query operations.
+- Query metrics showing index utilization, document load, output count, and scan behavior.
+- Transactional batch operation count, payload size, and single-partition proof.
+- SDK retry, timeout, connection mode, and diagnostics logging behavior.
+
+## When to push back
+
+Push back when the user wants a schema without access patterns, a partition key without cardinality proof, a critical cross-partition query, a cross-partition transaction, or an RU estimate with no measurement plan.

package/skills/azure/azure-cosmosdb-application-developer/references/mcp-and-evidence.md

@@ -1,31 +1,27 @@
-# MCP and evidence path
+# MCP and evidence path for Cosmos DB application design
 
-Use this reference only when you need to decide how to gather 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 screenshots, sanitized metrics, sanitized query results, or user-provided config excerpts
-2. **user-provided sanitized evidence** — redacted portal output, SDK code, IaC snippets, logs, or query text
-3. **documentation-based** — Microsoft Learn and official Azure MCP documentation
-4. **inference** — conclusions derived from patterns but not directly proven by evidence
+- "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-application-developer/references/official-sources.md

@@ -1,36 +1,23 @@
-# Official sources
+# Official sources for Azure Cosmos DB Application Developer
 
-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 data models or access patterns. Documentation proves documented Cosmos DB behavior; it does not prove the user's workload distribution, partition-key quality, RU budget, indexes, consistency setting, or latency profile.
 
-## 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 |
+| --- | --- |
+| [Partitioning and horizontal scaling in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning) | Partition key choice is a design-time scalability decision; require even distribution and access-pattern alignment. |
+| [Model and partition data in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/modeling-data) | Use for embedding vs referencing, entity boundaries, denormalization, and query-driven document design. |
+| [Understand request units consumption](https://learn.microsoft.com/en-us/azure/cosmos-db/understand-request-unit-consumption) | Ground RU costs in document size, indexing, consistency, query shape, and diagnostics. |
+| [Request Units in Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/request-units) | Use for provisioned throughput, multi-region RU behavior, and consistency tradeoffs. |
+| [Consistency levels](https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels) | Use for correctness and latency tradeoffs in read semantics. |
+| [Transactional batch operations](https://learn.microsoft.com/en-us/azure/cosmos-db/transactional-batch) | Use for ACID operations scoped to the same logical partition key and batch limits. |
+| [Optimize request cost for reads and writes](https://learn.microsoft.com/en-us/azure/cosmos-db/optimize-cost-reads-writes) | Use for point reads, query tuning, indexing, and request-charge checks. |
+| [Architecture best practices for Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db) | Use for Well-Architected design tradeoffs across reliability, cost, performance, security, and operations. |
 
-## Azure Cosmos DB
+## Source-grounding rules
 
-- Partitioning and horizontal scaling in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/partitioning
-- Data modeling in Azure Cosmos DB for NoSQL
-  https://learn.microsoft.com/en-us/azure/cosmos-db/modeling-data
-- Consistency levels in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/consistency-levels
-- Manage consistency levels in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-manage-consistency
-- Tuning query performance with Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/query-metrics
-- Architecture best practices for Azure Cosmos DB for NoSQL
-  https://learn.microsoft.com/en-us/azure/well-architected/service-guides/cosmos-db
-- Transactional batch in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/transactional-batch
-- Find request unit charge in Azure Cosmos DB
-  https://learn.microsoft.com/en-us/azure/cosmos-db/find-request-unit-charge
-
-## Grounded insights used by this skill
-
-- Do not trust generic NoSQL advice unless it matches Azure Cosmos DB partitioning and consistency behavior.
-- Runtime-exposed Azure MCP tools are truth; documentation does not prove current client exposure.
+- Do not approve a partition key without access-pattern evidence.
+- Do not recommend joins or cross-partition queries as the default path.
+- Treat RU estimates as workload-dependent; require measured `RequestCharge` or metrics for precision.
+- Keep API scope explicit: this skill defaults to Azure Cosmos DB for NoSQL unless the user names another API.

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"
 }