@raishin/vanguard-frontier-agentic 2.8.0 → 2.10.0

package/skills/azure/azure-app-service-production-readiness/SKILL.md

@@ -4,8 +4,8 @@ description: Review Azure App Service and Web Apps for production readiness acro
 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
 ---
 
@@ -28,7 +28,7 @@ Force clarity on:
 
 Default posture:
 
-- Prefer live evidence from official Azure MCP capabilities when they exist and are confirmed in the active runtime.
+- Prefer Microsoft Learn documentation through the user's configured documentation MCP; use sampled read-only Azure evidence when it is safely available.
 - Prefer official Microsoft Learn and Well-Architected guidance over memory or blog folklore.
 - Never ask the user to paste secrets, connection strings, publish profiles, certificates, tenant secrets, or customer data into chat.
 - Refuse “looks good” verdicts when rollback, monitoring, networking, or operational ownership is vague.
@@ -52,7 +52,7 @@ Do not use this skill 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 access, broad scope, destructive changes, and hand-wavy production claims.
 - Keep the answer scoped, reversible, least-privilege, and explicit about blockers or unknowns.
@@ -61,7 +61,9 @@ Do not use this skill 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/app-service-production-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, 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-app-service-production-readiness/metadata.json

@@ -28,12 +28,11 @@
     "https://learn.microsoft.com/en-us/azure/app-service/manage-backup",
     "https://learn.microsoft.com/en-us/azure/app-service/configure-zone-redundancy",
     "https://learn.microsoft.com/en-us/azure/reliability/reliability-app-service",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/",
-    "https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/azure-app-service"
+    "https://learn.microsoft.com/en-us/azure/architecture/web-apps/app-service/architectures/baseline-zone-redundant"
   ],
-  "security_notes": "Do not confuse plan SKU with readiness, public access restrictions with true private ingress, or backup configuration with recovery readiness. Prefer managed identity and Key Vault references over embedded secrets, treat app settings as sensitive, and do not invent unsupported Azure MCP namespaces or operations.",
-  "last_verified": "2026-04-27",
+  "security_notes": "Do not confuse plan SKU with readiness, public access restrictions with true private ingress, or backup configuration with recovery readiness. Prefer managed identity and Key Vault references over embedded secrets, treat app settings as sensitive, and do not invent unsupported configured Azure evidence namespaces or operations.",
+  "last_verified": "2026-06-05",
   "path": "skills/azure/azure-app-service-production-readiness",
   "author": "github: Raishin",
-  "version": "0.1.0"
+  "version": "0.1.3"
 }

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

@@ -0,0 +1,61 @@
+# App Service production operations
+
+## What people get wrong
+
+- They treat App Service as production-ready because it is PaaS. The workload still needs health, scaling, network, identity, release, and recovery design.
+- They trust slots without checking warm-up, sticky settings, dependency compatibility, and rollback drills.
+- They confuse VNet integration with private ingress. VNet integration controls outbound access; private endpoint and access restrictions control inbound exposure.
+- They put secrets in app settings instead of using managed identity and Key Vault references.
+- They configure backup but never prove restore, especially for state stores outside the app.
+
+## Officially grounded service shape
+
+Microsoft Learn frames App Service readiness around Well-Architected pillars. Production web apps need appropriate plan tier and instance count, health checks, diagnostics, HTTPS/TLS, managed identity, private networking where needed, deployment slots for release safety, autoscale, zone or regional resilience where required, and clear backup/restore ownership.
+
+## Non-negotiable design rules
+
+1. Use multiple instances for production workloads unless the business explicitly accepts single-instance risk.
+2. Enable health check with a path that proves critical dependency readiness without leaking sensitive data.
+3. Use managed identity and Key Vault references for secrets; never normalize pasted secrets.
+4. Validate inbound and outbound networking separately.
+5. Use staging slots for risky deployments and prove swap/rollback behavior.
+6. Use native database backup/restore for linked state stores; do not rely on App Service backup as a database recovery strategy.
+7. Enable diagnostics, metrics, alerts, and operator runbooks before go-live.
+
+## Minimal safe implementation flow
+
+1. Inventory app, plan, OS, region, tier, instances, deployment model, and dependencies.
+2. Verify ingress: public endpoint, access restrictions, private endpoint, DNS, Front Door/Application Gateway, WAF, and SCM exposure.
+3. Verify outbound: VNet integration, route-all, DNS, private endpoints, Key Vault, database, storage, registry, and firewall paths.
+4. Verify identity and secrets: system/user-assigned identity, Key Vault role or access policy, slot-specific references, and no embedded secret values.
+5. Verify release: staging slot, warm-up path, swap with preview if needed, sticky settings, rollback, and smoke tests.
+6. Verify resilience: health check, auto-heal, autoscale, zone/multiregion posture, backup, restore test, and dependency retry/circuit breakers.
+7. Deliver go/no-go with blockers.
+
+## High-risk assumptions to kill
+
+- App Service being managed PaaS does not prove production readiness; plan sizing, instance count, health checks, release safety, and dependency recovery still matter.
+- A staging slot is not a rollback plan unless sticky settings, warm-up path, smoke tests, and swap reversal are rehearsed.
+- VNet integration is outbound connectivity only; it does not provide private inbound access to the app.
+- App Service backup does not restore every surrounding dependency, network feature, identity, alert, or deployment slot.
+- A green health endpoint is weak evidence if it does not represent critical dependency readiness or if it leaks sensitive internals.
+
+## Safe command/code verification targets
+
+- Inspect IaC for plan SKU, worker count, zone redundancy, Always On, health check path, autoscale rules, diagnostics, and backup configuration.
+- Review deployment automation for staging-slot deployment, smoke testing, swap operation, rollback operation, and tagged container/image provenance.
+- Check app configuration for Key Vault references, managed identity use, slot-specific settings, no embedded secrets, and SCM access restrictions.
+- Validate templates distinguish private endpoint inbound access from VNet integration outbound access and include private DNS where required.
+- Review restore/runbook evidence for app content, configuration, custom domains, TLS, identities, networking, databases, and alerts instead of assuming one backup covers all.
+
+## Safe verification targets
+
+- Plan SKU/tier, worker count, autoscale rules, Always On, health check, and auto-heal.
+- Slot list, slot settings, traffic routing, swap behavior, and rollback evidence.
+- Public network setting, access restrictions, private endpoints, DNS, reverse proxy, and SCM restrictions.
+- Managed identity, Key Vault reference resolution, network-restricted vault access, and config separation.
+- Diagnostic settings, App Insights, alerts, log retention, backup schedule, and restore test results.
+
+## When to push back
+
+Push back on production launch if rollback is manual guesswork, health check is absent, public access is unexplained, secrets are embedded, linked database backup is assumed, or no one owns alerts and restore drills.

package/skills/azure/azure-app-service-production-readiness/references/mcp-and-evidence.md

@@ -1,39 +1,27 @@
-# MCP and Evidence Path
+# MCP and evidence path for App Service production operations
 
-## Official Azure MCP Linkage
+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.
 
-Use only official Azure MCP capabilities that are actually exposed in the active client runtime. Do not invent namespaces or pretend undocumented tools exist.
+## Evidence ladder
 
-Known official linkage relevant to this role, based on Microsoft documentation:
+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.
 
-- `appservice` for web app details, app settings, deployment details, detectors, and App Service diagnostics actions.
-- `monitor` for logs and metrics if the runtime exposes Azure Monitor tools.
-- `resourcehealth` for current health events if the runtime exposes Azure Resource Health tools.
-- `advisor` for recommendation discovery if the runtime exposes Azure Advisor tools.
-- `pricing`, `quota`, `group`, and `subscription` can help with supporting evidence when exposed.
+## Rules
 
-Rules:
+- 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.
 
-- Treat `appservice` as useful but incomplete. Official documentation shows App Service MCP support for app details, settings, deployments, detectors, diagnostics, and database connection operations; it does not prove first-class slot, VNet, private endpoint, or plan-capacity mutation tooling in MCP.
-- If a needed capability is generic or ambiguous, say so explicitly and switch to documentation-grounded review instead of hallucinating a tool path.
-- Treat secret-bearing outputs, especially app settings, as sensitive even when a tool can retrieve them.
-- Distinguish read-only evidence gathering from mutating operations such as updating app settings.
+## Final-answer evidence language
 
-## Platform-Agnostic Execution
+Use phrases like:
 
-This skill must work on macOS, Windows, Linux, and MCP-only clients.
-
-- Prefer evidence categories, architecture decisions, and operator checks over shell-specific commands.
-- When examples are useful, use placeholders such as `<subscription>`, `<resource-group>`, `<web-app>`, `<plan>`, `<slot>`, and `<vnet-subnet>`.
-- Adapt Azure CLI, PowerShell, IaC, or portal-specific steps only after the user’s actual toolchain is known.
-- Keep recommendations portable across code apps and custom-container apps unless the runtime model is already fixed.
-
-## Documentation Fallback When Live Data Is Unavailable
-
-Live Azure evidence beats static guidance for current-state validation. If live inspection is unavailable, incomplete, unsafe, or denied:
-
-- fall back to the Microsoft Learn and Well-Architected references listed above;
-- ask for sanitized architecture diagrams, slot configuration summaries, dependency maps, redacted app settings keys, alert inventories, or runbook excerpts when current-state proof is required;
-- label each conclusion as `live evidence`, `documentation-based`, `user-provided sanitized evidence`, or `inference`;
-- do not claim the app is production-ready merely because the target SKU supports a feature;
-- do not claim a feature is enabled in the user’s environment unless it was confirmed live.
+- "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-app-service-production-readiness/references/official-sources.md

@@ -1,22 +1,23 @@
-# Official Sources
+# Official sources for Azure App Service Production Readiness
 
-## References
+Use Microsoft Learn documentation through the user's configured documentation MCP to ground App Service reviews. Documentation proves service guidance; it does not prove the user's app settings, plan SKU, network routes, diagnostics, backup success, or production readiness.
 
-Load these only when needed:
+## Primary Microsoft Learn sources
 
-- [Architecture best practices for Azure App Service (Web Apps)](https://learn.microsoft.com/en-us/azure/well-architected/service-guides/app-service-web-apps) — use for pillar-based production design tradeoffs and shared-responsibility framing.
-- [Deployment best practices](https://learn.microsoft.com/en-us/azure/app-service/deploy-best-practices) — use for source/build/deploy separation, slot-first rollout, and anti-pattern detection.
-- [Set up staging environments in Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/deploy-staging-slots) — use for slot behavior, swap boundaries, and rollback realism.
-- [Best practices for Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/app-service-best-practices) — use for runtime, scaling, cert, and diagnostics guidance.
-- [Scale up an app in Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/manage-scale-up) — use for plan-tier capability questions and scale-up tradeoffs.
-- [Enable virtual network integration](https://learn.microsoft.com/en-us/azure/app-service/configure-vnet-integration-enable) — use for outbound private reachability requirements and subnet constraints.
-- [Manage App Service virtual network integration routing](https://learn.microsoft.com/en-us/azure/app-service/configure-vnet-integration-routing) — use when outbound routing, image pulls, backup, content share, or managed-identity pathing matters.
-- [Use private endpoints for Azure App Service apps](https://learn.microsoft.com/en-us/azure/app-service/overview-private-endpoint) — use for inbound private access, subnet separation, and public exposure reduction.
-- [App Service access restrictions](https://learn.microsoft.com/en-us/azure/app-service/overview-access-restrictions) — use for public-endpoint filtering and to avoid confusing it with private-endpoint controls.
-- [Use Key Vault references as app settings](https://learn.microsoft.com/en-us/azure/app-service/app-service-key-vault-references) — use for managed-identity-based secret retrieval, slot-setting guidance, and rotation caveats.
-- [Monitor App Service instances by using Health check](https://learn.microsoft.com/en-us/azure/app-service/monitor-instances-health-check) — use for health endpoint expectations, unhealthy-instance behavior, and swap implications.
-- [Back up and restore your app in Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/manage-backup) — use for tier-dependent backup and restore constraints.
-- [Configure App Service plans for zone redundancy](https://learn.microsoft.com/en-us/azure/app-service/configure-zone-redundancy) — use for zone support checks and minimum-instance expectations.
-- [Reliability in Azure App Service](https://learn.microsoft.com/en-us/azure/reliability/reliability-app-service) — use for SLA/reliability framing, shared responsibility, and recovery expectations.
-- [Azure MCP Server tools inventory](https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/) — use to verify official Azure MCP namespaces before naming them.
-- [Azure MCP Server tools for Azure App Service](https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/azure-app-service) — use to confirm the actual App Service MCP operations and their limits.
+| Source | Review implication |
+| --- | --- |
+| [Architecture best practices for Azure App Service Web Apps](https://learn.microsoft.com/en-us/azure/well-architected/service-guides/app-service-web-apps) | Ground reliability, security, cost, operational excellence, scaling, health check, slots, managed identity, diagnostics, and tradeoff guidance. |
+| [Reliability in Azure App Service](https://learn.microsoft.com/en-us/azure/reliability/reliability-app-service) | Use for shared responsibility, zone/region outage posture, backup, transient faults, maintenance, and SLA framing. |
+| [Deploy to deployment slots](https://learn.microsoft.com/en-us/azure/app-service/deploy-staging-slots) | Use for slot strategy, swap behavior, warm-up, sticky settings, and rollback checks. |
+| [Key Vault references for App Service](https://learn.microsoft.com/en-us/azure/app-service/app-service-key-vault-references) | Use for managed identity, secret reference, and network-restricted vault behavior. |
+| [Monitor App Service instances with health check](https://learn.microsoft.com/en-us/azure/app-service/monitor-instances-health-check) | Use for health path, unhealthy instance removal, and readiness checks. |
+| [App Service networking features](https://learn.microsoft.com/en-us/azure/app-service/networking-features) | Use for VNet integration, private endpoints, access restrictions, and outbound routing semantics. |
+| [Manage backup and restore in App Service](https://learn.microsoft.com/en-us/azure/app-service/manage-backup) | Use for backup support and linked-database backup deprecation caveats. |
+| [Baseline highly available zone-redundant web application](https://learn.microsoft.com/en-us/azure/architecture/web-apps/app-service/architectures/baseline-zone-redundant) | Use for production architecture, slots, package deployment, Key Vault references, private endpoints, and zone redundancy pattern. |
+
+## Source-grounding rules
+
+- A plan SKU recommendation from docs is not proof the current app is correctly scaled.
+- A configured slot in code is not proof of safe swap. Validate sticky settings, warm-up, health, and rollback evidence.
+- A private endpoint is not proof of private-only app posture. Check public access/access restrictions, DNS, reverse proxy path, and outbound dependencies.
+- Backup configured is not recovery proven. Require restore test evidence.

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