# Documentation and Evidence Path

## Preferred evidence order

1. Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior.
2. Sampled read-only Azure evidence, when safely available, for current configured-environment observations.
3. Sanitized user-provided evidence.
4. Clearly labeled inference.

## What each evidence type can prove

- Microsoft Learn documentation can prove documented service behavior, supported concepts, limitations, and recommended patterns.
- Sampled read-only evidence can prove the sampled configured state at the time observed.
- Sanitized user evidence can prove only what the snippet shows.
- None of these alone prove broad regional availability, future success, full account posture, or production readiness.

## Safe usage pattern

- State whether each claim is documentation-based, sampled-current-state, user-provided, or inference.
- Use read-only queries before recommending changes.
- Do not include sensitive internal identifiers, tenant identifiers, subscription identifiers, or secrets in committed docs or final findings.
- If no sampled evidence is available, say the review is documentation-based and list the exact evidence still needed.

# Azure Network Topology Operations

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

- Drawing hubs and spokes without route tables, DNS, and ownership boundaries.
- Assuming peering is transitive.
- Centralizing every flow through a firewall without proving latency, SNAT, throughput, and failure-domain impact.
- Ignoring private endpoint DNS when adopting Private Link.
- Letting workload teams and platform teams both own the same control without decision authority.

## Officially grounded service shape

Microsoft Learn evidence says hub-spoke topology uses a hub for shared network services and cross-premises connectivity, while spokes isolate workloads and may live across subscriptions and environments. Peering is nontransitive, DNS is a common hub-spoke dependency, forced tunneling and UDRs can centralize inspection, and regional hubs reduce blast radius. Virtual WAN is a managed alternative with different routing, scale, and operational tradeoffs.

- Hub virtual networks host shared services such as gateways, firewall, Bastion, DNS, and egress/ingress controls.
- Spoke virtual networks isolate workloads and usually peer to one regional hub.
- Spoke-to-spoke traffic needs explicit peering, direct connectivity, Virtual Network Manager, or routing through an NVA/firewall.
- DNS resolution must align with Private Link, cross-premises routing, and firewall FQDN rules.
- Virtual WAN can replace customer-managed hubs when managed transit and scale tradeoffs fit.

## Non-negotiable design rules

- Start with traffic flows, ownership, regions, and failure domains before choosing topology.
- Prove routing symmetry and DNS behavior for every critical path.
- Keep hubs regional unless cross-region routing is explicitly designed and monitored.
- Use direct spoke connectivity only for justified same-workload or same-environment flows.
- Separate platform-owned guardrails from workload-owned network controls.

## Minimal safe implementation flow

- Scope regions, subscriptions, hubs, spokes, shared services, cross-premises links, and private connectivity.
- Map flows: north-south, east-west, management, DNS, private endpoint, ingress, egress, and break-glass.
- Review peering, UDRs, gateway transit, firewall/NVA, DNS resolver, and monitoring design.
- Rank risks by blast radius: DNS, routing loops, asymmetric paths, firewall bottleneck, and shared-service outage.
- Return a target topology or remediation sequence with assumptions and verification evidence.

## High-risk assumptions to kill

- A hub-spoke diagram without route tables, DNS paths, security rules, and ownership is not an architecture review.
- Virtual network peering is nontransitive; spoke-to-spoke paths need explicit design through peering, Virtual Network Manager, or routed inspection.
- Central firewall inspection can create SNAT, throughput, latency, DNS, and blast-radius risks that must be measured or bounded.
- Private endpoint adoption without private DNS design will fail in ways that look like application or firewall issues.
- Cross-region hubs and shared services reduce duplication but can expand failure domains unless regional isolation is deliberate.

## Safe command/code verification targets

- Verify hub, spoke, region, subscription, route table, peering, gateway transit, DNS, firewall/NVA, and Private Link evidence for every critical flow.
- Check whether direct spoke connectivity is justified by same-workload or same-environment needs.
- Validate forced tunneling, forwarded traffic settings, SNAT capacity, firewall logs, and Network Watcher coverage.
- Confirm private DNS zone links/resolvers for private endpoints and cross-premises consumers.
- Require connection tests or sampled path evidence before approving production topology claims.

## Safe verification targets

- Every spoke has intended hub, route table, DNS path, and ownership.
- Private endpoint DNS zones and resolvers are designed for all consuming networks.
- Firewall/NVA throughput, SNAT, logging, and failover fit expected traffic.
- Cross-premises and inter-spoke paths are explicit and tested.
- Network Watcher, diagnostics, flow logs, and connection monitors cover critical paths.

## When to push back

- The user wants topology approval without route and DNS evidence.
- A single shared hub creates unacceptable blast radius.
- Private endpoint adoption ignores DNS resolution.
- Forced tunneling will break PaaS, update, or control-plane dependencies.

# Official Sources

Use these sources to ground the skill. Microsoft Learn documentation proves documented Azure behavior; it does not prove the user's tenant, subscription, RBAC, quota, migration project, network, telemetry, deployed resources, or production readiness.

## Primary Microsoft Learn sources

- https://learn.microsoft.com/azure/architecture/networking/architecture/hub-spoke
- https://learn.microsoft.com/azure/architecture/networking/architecture/hub-spoke-virtual-wan-architecture
- https://learn.microsoft.com/azure/cloud-adoption-framework/ready/landing-zone/design-area/network-topology-and-connectivity
- https://learn.microsoft.com/azure/architecture/networking/guide/private-link-hub-spoke-network
- https://learn.microsoft.com/azure/dns/private-resolver-architecture
- https://learn.microsoft.com/azure/virtual-network-manager/overview

## Grounding notes

- Documentation-based claim: Microsoft Learn evidence says hub-spoke topology uses a hub for shared network services and cross-premises connectivity, while spokes isolate workloads and may live across subscriptions and environments. Peering is nontransitive, DNS is a common hub-spoke dependency, forced tunneling and UDRs can centralize inspection, and regional hubs reduce blast radius. Virtual WAN is a managed alternative with different routing, scale, and operational tradeoffs.
- Current-state claim: requires sampled read-only Azure evidence or sanitized user-provided evidence.
- Inference: allowed only when labeled and tied to observed fields or documented behavior.
- Do not include sensitive internal identifiers or secret material in findings.

## Source use rules

- Prefer Microsoft Learn documentation through the user's configured documentation MCP for current Azure service behavior.
- Use sampled read-only Azure evidence only to validate current configured-environment observations.
- If documentation and sampled evidence appear to conflict, report both and stop short of a production-ready verdict.
- Re-check official sources before changing high-risk guidance, because cloud behavior and feature availability can change.

# Safety Checklist

## Evidence labels

- `documentation-based`: grounded in Microsoft Learn or listed official documentation.
- `sampled-current-state`: grounded in read-only Azure observations from the user's configured tools.
- `user-provided`: grounded in sanitized snippets supplied by the user.
- `inference`: reasoned from evidence but not directly proven.

## Mutation boundary

- Default to read-only review.
- Do not perform create, update, delete, activate, approve, cancel, deactivate, migrate, cut over, route, peer, deploy, alert, suppress, or configuration changes unless the user explicitly asks and approval is clear.
- Prefer preview, assessment, status, list, show, query, activity-log, dependency, and diagnostic evidence before any mutation.

## Credential and data boundary

- Never ask users to paste credentials, tokens, tenant IDs, subscription IDs, customer data, private keys, appliance secrets, migration inventory dumps, log payload secrets, or raw environment dumps.
- Summarize sensitive evidence by field presence, control state, and risk; do not reproduce secret material.

## Risk gates

- Stop on ambiguous target, ambiguous principal, missing approval, missing owner, missing rollback, stale assessment, incomplete dependency mapping, unclear routing, or missing telemetry for high-impact assets.
- Separate documented product behavior from sampled configured-environment evidence.

## Asset-specific hard line

Do not recommend flat or over-centralized network patterns by default. Always address routing, DNS, shared-service blast radius, inspection path, private connectivity, and platform-versus-workload control boundaries before calling a topology safe.

# Workflow and Output Contract

## Execution flow

1. Scope the exact target, environment boundary, owner, requested decision, and evidence available.
2. Load `official-sources.md`, then the component operations guide for service behavior and risk gates.
3. Gather sampled read-only evidence only when available and safe.
4. Compare observed posture against documented behavior, least-privilege expectations, and operational safety rules.
5. Return a verdict with evidence level, blockers, safe next actions, and open questions.

## Required output

- `verdict`: pass, warn, fail, or blocked.
- `evidence_level`: documentation-based, sampled-current-state, user-provided, inference, or mixed.
- `scope`: what was reviewed and what was not reviewed.
- `blockers`: issues that prevent a safe or production-ready conclusion.
- `findings`: severity-labeled risks with source labels.
- `safe_next_actions`: reversible actions first; mutation only with explicit approval.
- `open_questions`: missing facts that would change the verdict.

## Stress checks

- What assumption would make this recommendation unsafe?
- Which identity, migration, network, telemetry, route, or dispatch decision has the largest blast radius?
- What evidence would disprove the claimed readiness?
- Is the answer accidentally treating documentation as configured-environment proof?

## Response discipline

Use Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior. Use sampled read-only Azure evidence only for current configured-environment observations and label it as sampled evidence.