Imported from microsoft/powerplatform-build-tools (.claude/skills/debug-agent/SKILL.md). Install upstream with npx skills add microsoft/powerplatform-build-tools --skill debug-agent. Copyright stays with the author.

Debug Agent

Diagnose a pipeline failure or customer issue end-to-end. Accepts a log file path, pasted error text, ADO work item ID, or GitHub issue URL. Determines ownership, resolves if PPBT-owned, or produces a precise triage package for the right team.

Invoke as: /debug-agent <log-file-path | error-text | issue-url | ado-id>

Works autonomously through all steps. One exception: pauses to request pipeline logs if they are referenced in an ICM/work item but not yet provided — log evidence is required before classifying the failure layer.

Step 0 — Ingest the input

Determine input type:

• File path (.txt, .log, or similar): read it with the Read tool
• ADO work item (dev.azure.com/... URL or bare integer): az boards work-item show --id <id> 2>&1
• GitHub issue (github.com/.../issues/<n>): gh issue view <n> --comments 2>&1
• Pasted text: use as-is

Extract and print:

Input summary:
- Type: <file | ado | github | text>
- Task/tool identified: <name from log header, or "unknown">
- Error snippet: <first clear error line, or "none found">
- Timestamp range: <start → end>
- Deployment result: <SUCCESS | FAILED | unknown>

Step 0b — Check for missing logs

If input is an ICM or ADO work item AND any of the following are true:

• Custom field LogsAttached = "Yes"
• Description mentions "logs attached" or "see attachment"
• Issue cannot be diagnosed from text alone (no error snippet, no pac CLI output visible)

AND no log file path or log content was provided by the user:

→ STOP. Prompt the user:

Pipeline logs are attached to this ICM/work item but aren't accessible via API.
Please download the logs from the portal and provide the folder path.
Example: C:\Users\<you>\Downloads\

Once you share the path, I'll read the logs and continue the analysis from Step 1.

Do not proceed to Step 1 until log content is available. Do NOT classify the failure layer, assign ownership, or draw conclusions based solely on the ICM title or description — log evidence is mandatory. If the user confirms no logs exist or they are unavailable, continue with Confidence: low noted throughout.

Step 1 — Verify PPBT is involved

ADO (Azure DevOps) — PPBT task identifiers

Every PPBT v2 task follows the pattern: microsoft-IsvExpTools.PowerPlatform-BuildTools.<task-id>.<TaskClass>@2

PPBT signals (any one is sufficient):

• Task class matches any entry in the table above
• Author is Microsoft (not Wael Hamze or other community authors)
• Log contains POWERPLATFORMTOOLS_PACCLIPATH or PP_TOOLS_AUTOMATION_AGENT
• pac CLI invoked: lines containing pac solution, pac auth, pac env, pac admin, pac package
• BuildTools.EnvironmentUrl pipeline variable present

GitHub Actions — PPBT action identifiers

All PPBT GitHub Actions use: microsoft/powerplatform-actions/<action-name>@v1

Not-PPBT signals — deflect immediately:

• Author: Wael Hamze → CRM Build Tools (community)
• Microsoft.Xrm.Tooling.* PowerShell → old XRM Tooling
• PackageDeployer PowerShell task (v12.x) → Wael Hamze legacy tooling
• Task version @v1 and no microsoft/powerplatform-actions prefix → unrelated action

If not PPBT: skip to Step 5 (non-PPBT triage) immediately.

Step 2 — Identify the failing task and classify the layer

2a — Map the failing task to its inputs

Use the tables below to check whether required inputs are present in the log or YAML.

Helper tasks

Tool Installer (tool-installer) — must be FIRST task in every pipeline/workflow

• No required inputs beyond defaults
• Critical: if missing → all other tasks fail with "pac.exe not found" or POWERPLATFORMTOOLS_PACCLIPATH not set
• Optional: AddToolsToPath: true (adds pac to PATH for script tasks)

WhoAmI (whoami / whoAmI)

• Required: authenticationType + one of PowerPlatformEnvironment or PowerPlatformSPN
• GitHub: environment-url + auth credentials (user-name/password-secret OR app-id/client-secret/tenant-id)
• Use: connectivity check early in pipeline — failure here = auth or network issue, not solution issue

Quality check

Checker (checker / check-solution)

• Required: PowerPlatformSPN (SPN only — username/password NOT supported for checker)
• Required: RuleSet GUID
• Optional: UseDefaultPACheckerEndpoint (default true) — if false, must set CustomPACheckerEndpoint
• Output: SARIF file as pipeline artifact (ArtifactDestinationName)
• Common issue: checker fails for username/password connections — SPN required

Solution tasks

Import Solution (import-solution)

• Required: service connection + SolutionInputFile
• Key options: AsyncOperation: true (recommended for large solutions — avoids 4-min timeout), HoldingSolution (for upgrade pattern), UseDeploymentSettingsFile (for connection references + env vars)
• Common issue: sync import times out on large solutions → set AsyncOperation: true, MaxAsyncWaitTime: 60
• Common issue: connection references not set → use DeploymentSettingsFile

Export Solution (export-solution)

• Required: service connection + SolutionName + SolutionOutputFile
• Note: use solution Name not Display Name
• Managed: true exports as managed

Apply Solution Upgrade (apply-solution-upgrade)

• Required: service connection + SolutionName
• Use after Import with HoldingSolution: true

Pack / Unpack Solution — local operations, no service connection needed

• SolutionType: Managed | Unmanaged | Both

Set Solution Version (set-solution-version)

• Required: service connection + SolutionName + SolutionVersionNumber
• Tip: use $(Build.BuildId) as version number

Set Connection Variables (set-connection-variables)

• Sets pipeline variables: BuildTools.TenantId, BuildTools.ApplicationId, BuildTools.ClientSecret, BuildTools.DataverseConnectionString
• Username/password auth also requires ApplicationId and RedirectUri

Deploy Package (deploy-package)

• Required: service connection + PackageFile (.dll)
• GitHub Actions: Windows runner only (runs-on: windows-latest)

Environment management tasks

Create Environment (create-environment)

• Required: DisplayName, LocationName, EnvironmentSku, CurrencyName, LanguageName, DomainName
• Side effect: sets BuildTools.EnvironmentUrl pipeline variable — subsequent tasks use this automatically
• Note: BuildTools.EnvironmentUrl overrides any service connection URL for downstream tasks

Copy Environment (copy-environment)

• Required: TargetEnvironmentUrl
• CopyType: FullCopy (data + metadata) or MinimalCopy (metadata only)

Restore Environment (restore-environment)

• RestoreLatestBackup: true OR provide RestoreTimeStamp in mm/dd/yyyy hh:mm format

Export/Import Dataverse Data

• Schema file created via Configuration Migration tool
• Import accepts zip file or folder with data-schema.xml + data.xml

Power Pages tasks

• download-paportal / upload-paportal: requires WebsiteId GUID, optional ModelVersion (1=standard, 2=enhanced data model)

2b — When is it a PPBT bug (this repo)?

PPBT owns exactly the boundary between the ADO/GitHub pipeline and cli-wrapper. A bug is PPBT's if the wrong value reaches cli-wrapper or no value reaches cli-wrapper when the user configured the pipeline correctly.

PPBT owns it — fix in this repo — when:

PPBT does NOT own it — do not fix in this repo — when:

The test: ask "If the user configured the pipeline exactly right, would this still fail?" If yes → PPBT bug. If no → user error or downstream team.

2c — Classify the failure layer

Azure DevOps / GitHub Actions pipeline
  → [L1] user/pipeline config error (task ordering, missing inputs, wrong auth type)
  → [L2] PPBT code bug  (src/tasks/<name>/index.ts, getCredentials.ts, CliLocator.ts, etc.)
  → [L3] cli-wrapper bug  (@microsoft/powerplatform-cli-wrapper/dist/actions/)
  → [L4] pac CLI binary  (pac.exe / pac)
       └─ [L4-admin]  pac env/admin commands → admin-tools team
       └─ [L4-pac]    pac CLI crash / .NET exception → pac CLI team
       └─ [L4→L5]     pac correctly relays Dataverse error → CDS team
  → [L5] Power Platform API  (Dataverse / crm.dynamics.com)

2d — pac command → owning team (the critical split)

When pac CLI exits non-zero, the owning team depends on which pac command ran AND where the error originates:

pac command                    → Error origin               → Owner
─────────────────────────────────────────────────────────────────────────────
pac auth create/clear          → pac crashes / token error  → pac CLI (admin-tools)
pac auth create/clear          → wrong args from wrapper    → cli-wrapper (L3)

pac env create/delete/         → any pac-side failure       → admin-tools
  backup/restore/copy/reset

pac admin *                    → any failure                → admin-tools

pac solution import            → pac crashes / bad args     → pac CLI (admin-tools)
pac solution import            → Dataverse API error        → CDS / Solution Framework
pac solution import            → PVA component error        → pac CLI (IcM 604312672)

pac solution export            → pac crashes / bad args     → pac CLI (admin-tools)
pac solution export            → Dataverse API error        → CDS / Solution Framework

pac solution publish           → Dataverse API error        → CDS / Solution Framework

pac solution check             → checker service error      → Power Apps Checker team

pac package deploy             → pac crashes               → pac CLI (admin-tools)
pac package deploy             → Dataverse-side error       → CDS / Solution Framework

How to tell pac crash vs Dataverse error:

• pac crash / pac team: System.Exception, NullReferenceException, Unhandled exception, pac process exits with code 1 and no HTTP status in the message, InnerException in .NET stack trace
• Dataverse error / CDS team: HTTP status code in error (400, 403, 404, 500), OrganizationServiceFault, ErrorCode:, Microsoft.Crm.* in the message, ImportJobId, solution operation GUID, The import of solution messages
• Auth error / admin-tools or cli-wrapper: Azure AD / MSAL errors, AADSTS* error codes, interaction_required, token acquisition errors

Print:

Failing task: <task name>
pac command: <exact pac subcommand, e.g. "pac solution import">
Layer: <L1 | L2 | L3 | L4-pac | L4-admin | L4→L5>
Owner: <PPBT | cli-wrapper | pac-CLI/admin-tools | CDS/solution-framework | pipeline-config>
Error origin signal: <pac crash | Dataverse HTTP error | auth/AAD error | pipeline config>
Confidence: <high | medium | low>
Reasoning: <one sentence>

2d — pac CLI telemetry (L4-pac and L4→L5 only)

Run this step if and only if the layer is L4-pac or L4→L5.

pac CLI sends telemetry to PPUX Analytics via OneCollector. If the error output contains a Session ID like:

Sorry, the app encountered a non recoverable error and will need to terminate.
Session Id: 57f79894-80fb-4f44-8c94-8f800fc13e63,
Exception Type: System.ServiceModel.CommunicationException

Extract the Session ID and run the following Kusto query in PPUX Analytics to pull all telemetry events for that session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"

Additional useful queries:

Get the exact commands executed in the session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"
| where data_eventModifier == "Complete"
| extend eventInfo = parse_json(data_eventInfo)
| project eventInfo.command, timestamp

Get all errors in the session:

EventAll
| where data_appName == "ppdevtools-pac"
| where data_clientSessionId == "<session-id-from-error>"
| where data_eventModifier == "Failed" or data_severity >= 3
| project timestamp, data_eventName, data_eventInfo

If no Session ID is present in the log: note it and proceed — telemetry lookup not possible without it.

Print telemetry findings before continuing to Step 3.

Step 3 — Search for known issues (run all in parallel)

Extract 2–3 keywords from the error.

3a — GitHub issues

gh search issues --repo microsoft/powerplatform-build-tools \
  --state open --limit 10 "<keyword1> <keyword2>" 2>&1
gh search issues --repo microsoft/powerplatform-build-tools \
  --state closed --limit 5 "<keyword1> <keyword2>" 2>&1

3b — Merged PRs

gh search prs --repo microsoft/powerplatform-build-tools \
  --state merged --limit 5 "<keyword1> <keyword2>" 2>&1

3c — ADO work items

az boards query --wiql "
  SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate]
  FROM WorkItems
  WHERE [System.AreaPath] UNDER 'OneCRM\Client\UnifiedClient\AppLifeCycle\PPBT Extensions'
    AND [System.Title] CONTAINS '<keyword1>'
  ORDER BY [System.ChangedDate] DESC
" --output json 2>&1

3d — Local knowledge base

Read memory/ado-knowledge.md and check MEMORY.md known customer issues section.

Research summary (print before acting)

Known issue match: <issue/PR/ADO ID + title, or "none">
Accepted risk: <yes — <reason>, or "no">
Fix already shipped: <yes — in PR #<n> / pac version <v>, or "no">
Recommended action: <resolve | triage | deflect | update-pac | pipeline-fix>

If a confirmed fix already exists in a merged PR or shipped pac CLI version, report it and stop here.

Step 4 — Resolve (L1 pipeline config or L2 build-tools code)

L1 — Pipeline configuration fix (no code change)

Produce a precise fix instruction:

Pipeline fix required:
- Issue: <what's wrong>
- Fix: <exact YAML or UI step>
- Reference: <task name + parameter from Step 2 tables>

Common L1 fixes:

• Missing tool-installer → add PowerPlatformToolInstaller@2 as first step
• Import timeout → add AsyncOperation: true and MaxAsyncWaitTime: 60
• Wrong environment targeted → check BuildTools.EnvironmentUrl side effect from create-environment
• Checker with username/password → switch service connection to SPN
• Connection references missing → add UseDeploymentSettingsFile: true + provide DeploymentSettingsFile
• GitHub Actions: timeout installing pac CLI → add actions-install@v1 before other actions

L2 — Build-tools code fix (this repo)

1. Read the relevant src/tasks/<name>/index.ts and task.json
2. Make the minimal fix
3. npm run build 2>&1 — must pass
4. npm test 2>&1 — must pass (functional test failures are expected locally — not a blocker)
5. git commit -m "fix: <description> (#<work-item-id-if-known>)"
6. Hand off to /create-pr

Step 5 — Triage package (L3–L5 and non-PPBT)

Routing table

Triage package

This is mandatory output for ALL L3–L5 and non-PPBT cases. You MUST produce this block — do not skip it, summarize it, or replace it with prose.

For non-PPBT deflects (Wael Hamze, XRM Tooling, ADO Server 2020), fill in:

• Route to: Deflect to CSS / community tool owner
• ADO area path: N/A
• PPBT is not the root cause because: — cite the exact log signal that proves it (author, task class, tool name, absence of PPBT signals)

═══════════════════════════════════════════════════════
TRIAGE PACKAGE
═══════════════════════════════════════════════════════
Route to:        <team name | "Deflect — community tool">
ADO area path:   <path, or N/A>
GitHub repo:     <repo, or N/A>

Issue summary:
  <2–3 sentence plain-English description of what failed and where>

Reproduction evidence:
  Platform:      <ADO | GitHub Actions>
  Task/Action:   <name + version>
  pac CLI ver:   <version from log, or unknown>
  Auth type:     <SPN | Username/Password | Workload Identity Federation>
  Environment:   <cloud / region if visible>
  Error line:    <exact log line that proves the failure>
  Timestamp:     <ISO timestamp>

PPBT is not the root cause because:
  <one sentence — e.g. "pac CLI exited with code 1 after a Dataverse HTTP 500 on the import endpoint">

Suggested next steps for the receiving team:
  1. <action>
  2. <action>

Related known issues:
  <ADO ID / GH issue / IcM, or "none found">

Log file / evidence:
  <file path, or "pasted text — see conversation">
═══════════════════════════════════════════════════════

Step 6 — Outcome summary

Always end with a plain-English paragraph covering:

• What failed and where in the call chain
• Whether PPBT owns it
• What was done (fix applied / triage package / deflected)
• Any follow-up needed from the user

Quick-reference: authentication types

Quick-reference: task ordering rules

tool-installer / actions-install     ← MUST run first (sets POWERPLATFORMTOOLS_PACCLIPATH)
      │
      ├── whoAmI                     ← optional connectivity check
      │
      ├── create-environment         → sets BuildTools.EnvironmentUrl (auto-used by downstream tasks)
      │         │
      │         ├── import-solution  ← use AsyncOperation:true for large solutions
      │         ├── apply-solution-upgrade  ← only after import with HoldingSolution:true
      │         ├── export-solution
      │         ├── pack-solution / unpack-solution  (local, no connection needed)
      │         ├── publish-customizations
      │         ├── set-solution-version
      │         ├── checker          ← SPN only, no username/password
      │         └── deploy-package   ← Windows runner only (GitHub Actions)
      │
      ├── backup-environment → restore-environment
      ├── copy-environment
      └── delete-environment

Quick-reference: common error → fix mapping