Diagnose Deployment

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 8075ef5705c5 · 18 Oct 2026Report an issue or request a re-scan

• Publishermicrosoft GitHub organizationOwner of the repository this skill is read from
• Source foldermicrosoft/power-platform-skills/plugins/power-pages/skills/diagnose-deploymentThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict8075ef5705c5A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches against a known failure catalog, and optionally auto-fixes identified issues. Use when asked to: "diagnose deployment", "debug…

---
name: diagnose-deployment
description: >-
  Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches
  against a known failure catalog, and optionally auto-fixes identified issues. Use when
  asked to: "diagnose deployment", "debug deployment", "deployment failed", "show
  deployment errors", "fix deployment issues", "show upload logs", "why did my deploy fail",
  or "troubleshoot upload".
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus
---

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# diagnose-deployment

Surfaces and pattern-matches deployment errors against a known failure catalog. For each identified error with an available auto-fix, asks explicit user permission before applying any changes. Never auto-applies fixes without confirmation.

## Prerequisites

- Project root with `powerpages.config.json`
- PAC CLI installed (will report if missing)

## Phases

### Phase 1 — Verify Prerequisites and Locate Project

**Create all tasks upfront at the start of this phase.**

Tasks to create:
1. "Verify prerequisites and locate project"
2. "Collect deployment artifacts"
3. "Surface upload errors"
4. "Query solution import status"
5. "Diagnose and categorize findings"
6. "Offer auto-fixes"
7. "Present findings summary"

Steps:
1. Locate project root: search for `powerpages.config.json` in cwd and parent directories
2. Check PAC CLI: `pac --version` (report version or "not installed")
3. Check PAC CLI auth: `pac env who` (report environment URL or "not authenticated")
4. Check Azure CLI: `az account show` (report subscription or "not logged in")

Auth failures are non-blocking — report them as findings, continue collecting other artifacts.

### Phase 1.5 — Ground in current ALM documentation

> Reference: `${PLUGIN_ROOT}/references/alm-docs-grounding.md`

Cap this step at ~30 seconds. If MCP search / fetch errors out, log a one-line note and continue — this skill must remain runnable offline.

1. Run `microsoft_docs_search` with the query: `Power Pages deployment errors solution import troubleshooting`.
2. Fetch `https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm` (and at most one sister page on troubleshooting or known import errors) in parallel via `microsoft_docs_fetch`.
3. Extract a one-paragraph summary of what Microsoft Learn currently says about common deployment failures and their resolution. Compare against `${PLUGIN_ROOT}/references/deployment-error-catalog.md` and flag any new error patterns not yet captured in the catalog.
4. Use the summary to inform pattern-matching in Phase 5. If a new pattern is documented on Learn that isn't in the catalog, surface it to the user as a candidate addition rather than silently extending the catalog.

### Phase 2 — Collect Deployment Artifacts

Gather all available context:

1. Read `powerpages.config.json` — extract `siteName`, `websiteRecordId`, `compiledPath`
2. Check `.powerpages-site/` folder exists
3. Glob for manifest files: `.powerpages-site/*-manifest.yml` — list all found, note their environment hostnames
4. Check if `.solution-manifest.json` exists (for solution-related diagnostics)
5. Check if `docs/alm/last-import.json` exists (for recent import failures)
6. Check build output: confirm `{compiledPath}/` exists and is non-empty

Report: "Found project: `{siteName}`. Artifacts collected."

### Phase 3 — Surface Upload Errors

Re-run `pac pages upload-code-site` in capture mode to get fresh error output:

```bash
pac pages upload-code-site --rootPath "." 2>&1
```

> **Note**: This intentionally triggers the upload to capture any errors. If the upload succeeds cleanly, that is also a valid diagnostic result ("no errors found").

Capture stdout+stderr as a single string. Pass to `scripts/parse-deployment-errors.js`:

```bash
echo "{escaped-output}" | node "${PLUGIN_ROOT}/scripts/parse-deployment-errors.js"
```

Parse the JSON findings array. If the upload succeeded with no errors, note this and skip to Phase 5 with an empty findings list.

### Phase 4 — Query Solution Import Status

Only run if `.solution-manifest.json` exists.

1. Acquire Azure CLI token for environment URL
2. Check recent async operations (last 24 hours):
   ```
   GET {envUrl}/api/data/v9.2/asyncoperations?$filter=statecode eq 3 and statuscode eq 31 and createdon gt {yesterday}&$select=asyncoperationid,name,message,friendlymessage,statuscode,completedon&$orderby=completedon desc&$top=5
   ```
3. Check recent import jobs:
   ```
   GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3
   ```
4. If failed operations found, pass each `message` field through `parse-deployment-errors.js`

Skip gracefully if auth is not available (auth failure in Phase 1).

### Phase 5 — Auto-Diagnose Known Issues

Consolidate all findings from Phases 3 and 4. For each finding, categorize:

- **Error**: Blocks deployment
- **Warning**: May cause issues
- **Info**: Informational

Also add findings for missing artifacts discovered in Phase 2:
- Missing `websiteRecordId` → Error (patternId: `missing-website-record-id`)
- Empty build output → Error (patternId: `empty-build`)
- Multiple environment manifests → Warning (may indicate environment confusion)

Present all findings in a table:

| # | Severity | Type | Issue | Auto-fix? |
|---|---|---|---|---|
| 1 | Error | upload | JavaScript uploads blocked | Yes |
| 2 | Warning | config | Multiple manifest files found | No |

### Phase 6 — Offer Auto-Fixes

For each Error finding with `autoFixAvailable: true`, in order:

<!-- gate: diagnose-deployment:6.auto-fix | category=consent | cancel-leaves=nothing -->
> 🚦 **Gate (consent · diag

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/microsoft/power-platform-skills
git -C power-platform-skills checkout 8075ef5705c5

Works in

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source 8075ef5705c5

Questions about Diagnose Deployment

• github.com/microsoft/power-platform-skills/tree/main/plugins/pow — the audited source at commit 8075ef5705c5 and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology