# MCP and evidence path

Use this reference when deciding how to ground `azure-role-selector` 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, billing state, security posture, reliability 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-role-selector`.

## Microsoft Learn sources

- https://learn.microsoft.com/azure/role-based-access-control/overview
- https://learn.microsoft.com/azure/role-based-access-control/best-practices
- https://learn.microsoft.com/azure/role-based-access-control/built-in-roles
- https://learn.microsoft.com/azure/role-based-access-control/role-definitions
- https://learn.microsoft.com/azure/role-based-access-control/custom-roles
- https://learn.microsoft.com/azure/role-based-access-control/role-assignments-steps
- https://learn.microsoft.com/azure/role-based-access-control/scope-overview
- https://learn.microsoft.com/azure/role-based-access-control/role-assignments-steps#step-2-select-the-appropriate-role
- https://learn.microsoft.com/azure/role-based-access-control/rbac-and-directory-admin-roles

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

- 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, billing state, security posture, 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 Role Selection 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

- Starting from Owner or Contributor instead of required actions.
- Ignoring the difference between control-plane Actions and data-plane DataActions.
- Using a custom role when a narrower built-in role already fits.
- Assigning at subscription scope when resource or resource-group scope is enough.
- Using wildcard custom-role permissions that can expand with future provider operations.

## Officially grounded service shape

- Microsoft Learn evidence says Azure built-in roles expose Actions, NotActions, DataActions, and NotDataActions so reviewers can compare required permissions against role definitions.
- Role selection guidance says start with job-function roles, review service categories, choose the most restrictive role, and create a custom role only when no suitable built-in role exists.
- Control-plane authorization is handled through Azure Resource Manager, while data-plane authorization is handled by a resource provider or Azure Resource Manager depending on service behavior.
- Custom roles can include data actions, but roles with DataActions cannot be assigned at management group scope. Microsoft recommends explicit permissions instead of wildcards.

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

## Non-negotiable design rules

- Start from required operations, target resource, principal type, and duration.
- Separate management-plane and data-plane access before selecting a role.
- Prefer built-in job-function roles and narrow scope before custom roles.
- Use custom roles only with explicit Actions/DataActions and documented assignable scopes.
- Require a removal, expiry, or review path for the assignment.

## Minimal safe implementation flow

- Capture principal, target resource, operations, data access, environment, and duration.
- Map operations to resource provider actions and service built-in roles.
- Choose the narrowest role and scope; add data-plane role separately if required.
- If no built-in role fits, design an explicit custom role with narrow assignable scopes.
- Return selected role, scope, evidence level, risks, validation checks, and cleanup path.

## High-risk assumptions to kill

- A built-in role name alone proves least privilege; it does not unless its Actions/DataActions match the requested operations.
- Contributor is acceptable temporary access; temporary broad access still expands blast radius and needs expiry, approval, and removal evidence.
- Management-plane access includes data access; many services require separate data-plane roles or provider-specific authorization.
- Management group scope is a harmless convenience; data-action roles cannot be assigned there and broad inheritance is hard to unwind.
- A wildcard custom role is future-proof; it can silently expand when resource providers add operations.

## Safe command/code verification targets

- Inspect candidate role definitions with read-only role-definition commands or SDK calls and compare required Actions/DataActions to the task.
- List existing role assignments only at the proposed narrow scope and confirm no broader standing assignment already covers the same principal.
- Check whether the requested operation is management-plane, data-plane, or both before recommending one role.
- For custom-role drafts, lint JSON, require explicit permissions, confirm assignable scopes, and reject wildcard permissions unless Microsoft documentation proves no safer option.
- Treat Microsoft Learn documentation as service-behavior evidence; treat read-only authorization queries as sampled current-state evidence only.

## Safe verification targets

- Role definition contains only needed Actions/DataActions for the task.
- Assignment scope is no broader than the named resource set.
- Privileged administrator roles are avoided or explicitly justified.
- Custom role avoids wildcard permissions and has bounded assignable scopes.
- Access can be tested and removed without broad collateral impact.

## When to push back

- The user asks for Owner/Contributor because it is faster.
- The request mixes management-plane and data-plane access without naming both.
- The custom role depends on wildcard permissions.
- The target scope is broader than the requested task.

# Safety checklist

Use before recommending production Azure changes, access grants, security remediation, hierarchy moves, cost actions, reliability changes, or readiness conclusions for `azure-role-selector`.

## 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, billing changes, commitment purchases, hierarchy moves, 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 roles:** broad privileged roles, direct user grants, wildcard custom roles, missing PIM/time-bound controls, inherited scope surprises.
- **Security posture:** stored secrets, public exposure, missing managed identities, weak Key Vault boundaries, no diagnostic coverage, untracked policy exemptions.
- **Resource organization:** flat hierarchy drift, fake isolation via resource groups, subscription sprawl, weak ownership, policy inheritance surprises.
- **Cost:** optimizing recommendations without workload context, deleting resources without owner confirmation, buying commitments before rightsizing, ignoring licensing and reliability cost tradeoffs.
- **Reliability:** vague SLOs, untested recovery, overengineered topology, missing health model, no dependency mapping, unvalidated chaos or failover assumptions.

## 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-role-selector`.

## Workflow

1. **Classify the request**
   - Identify service/domain, resource scope, environment, production impact, and whether mutation or billing impact 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, diagnostic query, cost forecast, or staged rollout before mutation.
   - Require explicit approval for live, destructive, access, reliability, hierarchy, or billing-impacting 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, billing, quota, or posture 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, expiry, or reversal path where applicable