# MCP and evidence path

Use this reference when deciding how to ground `azure-private-endpoint-adoption-planner` 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-private-endpoint-adoption-planner`.

## Microsoft Learn sources

- https://learn.microsoft.com/azure/private-link/private-endpoint-dns-integration
- https://learn.microsoft.com/azure/private-link/private-endpoint-dns
- https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/private-link-and-dns-integration-at-scale
- https://learn.microsoft.com/azure/architecture/networking/guide/private-link-virtual-wan-dns-guide
- https://learn.microsoft.com/azure/dns/private-resolver-endpoints-rulesets
- https://learn.microsoft.com/azure/networking/foundations/network-foundations-overview

## 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 Private Endpoint Adoption 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 private endpoint as complete before DNS resolution is designed.
- Creating duplicate private DNS zones with the same name across VNets and hoping Azure merges records.
- Linking private DNS zones to the wrong VNets in hub-spoke or Virtual WAN topologies.
- Assuming central hub placement is always safer than workload-local endpoints.
- Ignoring private endpoint record lifecycle when endpoints are deleted or moved.

## Officially grounded service shape

- Microsoft Learn evidence says the service FQDN must resolve to the private endpoint IP, so DNS configuration is central to Private Link success.
- For peered hub-spoke workloads, Microsoft Learn calls for a single private DNS zone linked to all hub and spoke networks that need resolution.
- DNS zone groups associate private endpoints with private DNS zones and can manage records as endpoints change or are deleted, within documented limits.
- At scale, central private DNS zones, policy-driven DNS zone groups, DNS Private Resolver, conditional forwarding, and regional endpoint strategy become governance decisions.

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

- Design DNS before endpoint placement.
- Use the recommended private DNS zone name for each Azure service and avoid mixing unrelated services in one zone.
- Name every consumer VNet, peering path, hub, resolver, and on-premises forwarding dependency.
- Decide central versus workload-local endpoint placement from traffic flow, ownership, and regional resilience, not aesthetics.
- Require rollback checks for DNS records, VNet links, firewall/DNS proxy settings, and application connection strings.

## Minimal safe implementation flow

- Scope PaaS services, consumers, regions, subscriptions, VNets, and current DNS authority.
- Map resolution path from each consumer to the private endpoint FQDN and private IP.
- Choose endpoint placement and DNS zone ownership pattern.
- Define IaC or policy mechanism for DNS zone group creation and record lifecycle.
- Validate name resolution, connectivity, routing, monitoring, and rollback before broad rollout.

## High-risk assumptions to kill

- Private endpoint creation without DNS design is incomplete; Microsoft Learn is blunt that DNS is critical for correct private endpoint connectivity.
- Overriding an actively used public zone without forwarding can break existing public endpoint resolution.
- Same-name private DNS zones and mixed-service records can delete or conflict with records and cause intermittent resolution failures.
- Hub-hosted central DNS does not prove every spoke, on-premises resolver, and private endpoint consumer resolves through the intended path.
- A successful test from one VNet is not evidence for peered VNets, on-premises clients, hybrid DNS, or regional failover paths.

## Safe command/code verification targets

- Verify service-specific private DNS zone names, DNS zone groups, A records, VNet links, resolver/forwarder paths, and endpoint network interfaces.
- Test FQDN resolution to private IP from each consumer network, including hub, spoke, and on-premises paths where applicable.
- Check for duplicate same-name zones, mixed-service records, missing VNet links, and stale records after endpoint deletion or movement.
- Confirm firewall, DNS proxy, Private Resolver, and conditional forwarding behavior before broad rollout.
- Validate rollback by restoring DNS path, public access posture, connection strings, and endpoint record lifecycle.

## Safe verification targets

- Private DNS zones match Microsoft service-specific zone names.
- Required VNets are linked to the authoritative private DNS zones.
- On-premises or custom DNS forwards to the correct resolver path.
- Endpoint FQDN resolves to expected private IP from each consumer network.
- Deleting or moving endpoints has a defined DNS cleanup path.

## When to push back

- The design says “private endpoint enabled” but cannot explain DNS.
- Multiple same-name zones are proposed without record-management ownership.
- Virtual WAN DNS behavior is assumed to match traditional hub-spoke behavior.
- The rollout has no staged validation or rollback for application connectivity.

# Safety checklist

Use before recommending production Azure changes, access grants, network connectivity changes, deployment automation, resilience claims, or incident conclusions for `azure-private-endpoint-adoption-planner`.

## 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-private-endpoint-adoption-planner`.

## 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