dlm-diagnostics

by microsoft

Diagnose Microsoft Purview Data Lifecycle Management (DLM) issues in Exchange Online. Use this skill when a user reports: retention policy not applying to…

npx skills add https://github.com/microsoft/purview-dlm-mcp --skill dlm-diagnostics

Download ZIP GitHub

Try this skillSponsored

DLM Diagnostics

Investigate and resolve Microsoft Purview Data Lifecycle Management issues in Exchange Online. Follow the decision tree below to identify the correct troubleshooting guide, then load the matching reference file for step-by-step diagnostic instructions.

Prerequisites

Before running any diagnostic commands, ensure both PowerShell sessions are connected:

Connect-ExchangeOnline -UserPrincipalName '<admin@contoso.com>' -ShowBanner:$false
Connect-IPPSSession -UserPrincipalName '<admin@contoso.com>' -ShowBanner:$false

Safety Rules

Only execute read-only commands. Allowed cmdlet verbs: Get-*, Test-*, Export-*.

Never execute mutating commands — Set-*, New-*, Remove-*, Enable-*, Start-*, Invoke-* cmdlets must only be returned as text recommendations for the admin to review and run manually.

Decision Tree

Identify the reported symptom and load the matching reference:

Symptom	Reference
Policy shows Success but content is not retained or deleted on target workloads	retention-policy-not-applying.md
Policy status shows Error, PolicySyncTimeout, or PendingDeletion	policy-stuck-error.md
Archive mailbox exists but items stay in the primary mailbox	items-not-moving-to-archive.md
Archive is near 100 GB but no auxiliary archive is being created	auto-expanding-archive.md
User was deleted but mailbox was purged instead of becoming inactive	inactive-mailbox.md
Recoverable Items folder growing uncontrollably or SubstrateHolds is large	substrateholds-quota.md
Teams retention policy exists but messages remain visible past retention period	teams-messages-not-deleting.md
Both MRM and Purview retention on a mailbox causing unexpected behavior	mrm-purview-conflict.md
Adaptive scope includes wrong members, shows no members, or scope query not targeting correct users/sites	adaptive-scope.md
Auto-apply retention label policy not labeling content, stuck in simulation, or shows "Off (Error)"	auto-apply-labels.md
SharePoint site cannot be deleted because a retention policy or hold is blocking it	sharepoint-site-deletion-blocked.md

If the issue does not match a specific symptom above, or for ad-hoc investigations, see diagnostic-commands.md for a quick-reference of common diagnostic commands. For adaptive scope validation commands, see adaptive-scope.md.

Workflow

Identify the symptom from the user's description using the decision tree above.
Load the matching reference file — read it fully before starting the investigation.
Execute diagnostic commands step by step using the run_powershell MCP tool, following the reference guide's sequence.
Interpret results at each step — the reference guide explains what to look for and how each finding maps to a root cause.
Cross-reference — some guides link to sibling references (e.g., policy distribution failures link to policy-stuck-error.md). Load those when directed.
Report findings — summarize the root cause, present the root-cause confirmation table, and provide the recommended remediation actions as text for the admin to review.
Review the execution log — use the get_execution_log MCP tool to include a full audit trail of all commands run during the investigation.

Output Format

Present findings to the user in this structure:

## Investigation Summary

**Symptom:** <what was reported>
**Mailbox/Policy:** <target>

## Diagnostic Steps

✅/❌ Step N — <step name>
   Finding: <what was found>
   Command: <command that was run>

## Root Cause

<identified root cause from the reference guide's root-cause table>

## Recommended Actions

⚠️ These commands are NOT executed automatically. Review and run manually:
- <remediation command 1>
- <remediation command 2>