dlm-diagnostics
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-diagnosticsDLM 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_powershellMCP 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_logMCP 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>