# MCP and evidence path

Use this reference when deciding how to ground `azure-platform-automation-devops` guidance.

## Evidence order

1. Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior.
2. Sampled read-only Azure evidence when the user has configured it and current-state confirmation is necessary.
3. Sanitized user-provided evidence when no read-only evidence path is available.
4. Clearly labeled inference when evidence is incomplete.

## Boundaries

- Documentation evidence does not prove the user's tenant, subscription, RBAC, quotas, deployed resources, private connectivity, incident state, or production readiness.
- Sampled read-only evidence proves only the sampled configured environment and time window.
- User-provided evidence can be incomplete or stale; preserve uncertainty.
- Never ask for credentials, tokens, secrets, tenant IDs, subscription IDs, resource IDs, customer data, private keys, or raw incident payloads.

## Required phrasing

Use generic phrasing such as "Microsoft Learn documentation through the user's configured documentation MCP". Do not expose internal tool names, profile names, environment names, or local identifiers in committed docs.

# Official sources

Use this reference when grounding current Azure behavior for `azure-platform-automation-devops`.

## Microsoft Learn sources

- https://learn.microsoft.com/azure/azure-resource-manager/bicep/deploy-what-if
- https://learn.microsoft.com/training/modules/test-bicep-code-using-github-actions/
- https://learn.microsoft.com/training/modules/test-bicep-code-using-azure-pipelines/
- https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/
- https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/implementation-options
- https://learn.microsoft.com/azure/architecture/landing-zones/bicep/landing-zone-bicep
- https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/terraform-landing-zone

## Current documentation refresh (2026-06-04)

- Microsoft Learn documentation through the user's configured documentation MCP is the primary source for documented Azure behavior.
- Documentation evidence is not live customer-state evidence. It does not prove the user's tenant, subscription, RBAC, quotas, deployed resources, incident posture, private connectivity, automation state, or production readiness.
- Use sampled read-only Azure evidence only when the user has configured it and the task requires current-state confirmation. Label it as sampled evidence, not broad proof.

## Grounding rule

Docs explain service behavior. Current-state claims require sampled read-only evidence or sanitized user-provided evidence. If current state was not queried or shown, say so.

# Azure Platform Automation Operations

> Version note: Azure service behavior and tooling change over time. Verify exact command syntax, permissions, and feature availability against Microsoft Learn documentation through the user's configured documentation MCP before production use. Do not paste secrets or sensitive identifiers into commands, files, or chat.

Use this reference for current, source-grounded service behavior and the hard review gates that the lean `SKILL.md` intentionally does not carry.

## What people get wrong

- Treating a green pipeline as proof that a platform change is safe.
- Mixing bootstrap, shared platform, and workload deployments into one uncontrolled flow.
- Skipping what-if or equivalent preview because the template compiled.
- Assuming Bicep, Terraform, or a landing-zone accelerator is automatically the right answer.
- Putting publish profiles, client secrets, or service connection secrets into repo or chat.

## Officially grounded service shape

- Microsoft Learn evidence says Bicep what-if previews predicted resource changes without making changes and works at resource group, subscription, management group, and tenant scopes.
- What-if has real limits: nested template expansion limits, short-circuiting, unevaluated expressions, and possible noise from defaulted properties.
- Microsoft Learn training for Bicep delivery emphasizes linting, preflight validation, what-if checks, manual approval steps, and post-deployment verification.
- Azure landing-zone guidance separates platform foundations from workload adoption and supports multiple implementation options rather than one universal IaC path.

Documentation evidence proves documented Azure service behavior. It does not prove the user's tenant, subscription, RBAC, quotas, deployed resources, incident state, or production readiness.

## Non-negotiable design rules

- Classify bootstrap, platform, and workload scope before proposing a pipeline.
- Require lint, static validation, what-if or equivalent preview, human approval for risky changes, and post-deployment verification.
- Use least-privilege deployment identities scoped to the deployment boundary.
- Treat what-if output as evidence with limitations, not as absolute proof of safety.
- Refuse production rollout advice when rollback, blast radius, or approval ownership is missing.

## Minimal safe implementation flow

- Scope landing zone, subscriptions, management groups, target regions, IaC tool, and owner boundary.
- Separate bootstrap prerequisites from steady-state platform operations and workload delivery.
- Review identity, secrets, service connections, module source, state storage, and environment promotion model.
- Require lint, validation, what-if preview, approval, deployment, smoke checks, and rollback evidence.
- Return a go, no-go, or conditional-go verdict with blockers and verification targets.

## High-risk assumptions to kill

- A compiled template or green pipeline is not proof of safe platform change; preview, approval, and post-deploy verification are separate evidence gates.
- What-if is useful but imperfect; nested templates, unevaluated expressions, defaulted properties, and unsupported Deployment Stack what-if paths can hide risk or create noise.
- A deployment identity that can mutate management groups, subscriptions, networking, and workloads is a blast-radius problem unless explicitly justified and gated.
- Deployment Stacks add lifecycle ownership; action-on-unmanage and deny settings can detach, delete, or lock resources in ways normal release rollback will not undo.
- Secret-free automation is non-negotiable: service principals, publish profiles, client secrets, and tenant-specific identifiers do not belong in repo docs or chat.

## Safe command/code verification targets

- Verify Bicep/Terraform lint, schema/preflight validation, what-if/plan output, and manual approval for the exact deployment scope.
- Inspect preview output for creates, modifies, deletes, ignores, unevaluated expressions, deny settings, and action-on-unmanage behavior.
- Check deployment identity permissions against least privilege and target boundary before running automation.
- Confirm environment promotion, module source integrity, state storage, and secret handling are documented and enforced.
- Verify post-deployment smoke checks, drift checks, and rollback/redeploy limits before calling the platform path production-ready.

## Safe verification targets

- IaC lint and schema validation pass for the exact target scope.
- What-if preview or equivalent plan is reviewed for create, modify, delete, ignore, and unevaluated-expression risks.
- Deployment identity permissions match target scope and do not require broad Owner by default.
- Secrets are stored in approved secret stores or platform-protected variables, not repo files.
- Rollback or redeploy path is tested or explicitly bounded.

## When to push back

- A single pipeline can mutate management groups, subscriptions, networking, and workloads without gates.
- The user wants to deploy without reviewing preview output.
- Secrets or tenant-specific identifiers are requested in chat.
- The plan confuses application release rollback with platform rollback.

# Safety checklist

Use before recommending production Azure changes, access grants, network connectivity changes, deployment automation, resilience claims, or incident conclusions for `azure-platform-automation-devops`.

## Non-negotiables

- Do not ask for or print credentials, client secrets, certificates, private keys, access tokens, tenant IDs, subscription IDs, resource IDs, customer data, raw incident payloads, or environment-specific identifiers.
- Prefer Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior.
- Use sampled read-only Azure evidence only for current-state claims and label it as sampled evidence.
- Require explicit approval before recommending live mutation, broad access, destructive remediation, production deployment, DNS changes, failover, failback, or alert suppression.
- Keep recommendations least-privilege, reversible where possible, and scoped to the named resource or workload.
- Separate documentation-based claims, sampled evidence, user-provided evidence, and inference.

## Component risks

- **Identity and RBAC:** broad privileged roles, direct user grants, wildcard custom roles, missing PIM/time-bound controls, inherited scope surprises.
- **Automation and IaC:** missing preview, unreviewed delete/modify changes, overbroad deployment identities, unsafe secret handling, no rollback path.
- **Networking and Private Link:** DNS misconfiguration, duplicate private DNS zones, missing VNet links, resolver/forwarder gaps, route surprises, broken application connectivity.
- **Resilience and BCDR:** fantasy RTO/RPO, untested restore, undocumented failback, inaccessible DR assets, hidden single-region dependencies.
- **Health triage:** false provider attribution, unsupported resource health, ignored activity-log changes, sensitive incident payload exposure, broad remediation before blast-radius evidence.

## Evidence labels

Use `documentation-based`, `sampled read-only evidence`, `repo evidence`, `user-provided evidence`, or `inference`. Documentation alone never proves the user's live Azure environment.

# Workflow and output contract

Use this reference for full execution of `azure-platform-automation-devops`.

## Workflow

1. **Classify the request**
   - Identify service/domain, resource scope, environment, production impact, and whether mutation is requested.
   - Identify whether the task needs documentation-only guidance, sampled read-only current-state evidence, or sanitized user evidence.

2. **Ground in current sources**
   - Prefer Microsoft Learn documentation through the user's configured documentation MCP.
   - Read the component operations guide before issuing design, safety, or readiness conclusions.
   - Treat current-state claims as unproven unless supported by sampled read-only evidence or sanitized user-provided evidence.

3. **Stress-test the plan**
   - Kill broad permissions, vague ownership, missing rollback, missing validation, and unsupported production-readiness claims.
   - Separate facts from inference.
   - State blockers before recommendations.

4. **Recommend minimal safe action**
   - Prefer read-only inspection, preview, what-if, dry run, diagnostic query, or staged rollout before mutation.
   - Require explicit approval for live or destructive actions.
   - Keep the recommendation scoped and reversible where possible.

5. **Validate and hand off**
   - Name verification targets and evidence gaps.
   - Provide safe next actions and escalation criteria.
   - Do not claim tenant, subscription, resource, quota, or incident state that was not observed.

## Output contract

Return:

1. Scope and target
2. Evidence level: documentation-based, sampled read-only evidence, user-provided evidence, repo evidence, or inference
3. Key findings and risks
4. Blockers or missing evidence
5. Minimal safe next actions
6. Verification targets
7. Rollback, cleanup, or reversal path where applicable