feat(case-tool): add troubleshooting step for failed cases

skills/uipath-maestro-case/SKILL.md

@@ -84,6 +84,7 @@ Re-read `tasks.md` AND `caseplan.json` (Step 9.6). Then:
 | Edit caseplan.json directly | [references/case-editing-operations.md](references/case-editing-operations.md) |
 | Case JSON schema | [references/case-schema.md](references/case-schema.md) |
 | Surviving CLI commands (registry, validate, debug, runtime) | [references/case-commands.md](references/case-commands.md) |
+| Troubleshoot a failed case | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
 | Resolve task types from registry | [references/registry-discovery.md](references/registry-discovery.md) |
 | Wire inputs/outputs + cross-task refs + expression prefixes | [references/bindings-and-expressions.md](references/bindings-and-expressions.md) |
 | Configure connector activity / trigger / event | [references/connector-integration.md](references/connector-integration.md) |

skills/uipath-maestro-case/references/implementation.md

@@ -224,6 +224,20 @@ uip maestro case debug "<directory>/<solutionName>/<projectName>" --log-level de
 
 Requires `uip login`. Uploads to Studio Web, runs in Orchestrator, streams results.
 
+## Step 14a — Troubleshoot failed case
+
+When a debug or process run fails, read **[troubleshooting-guide.md](troubleshooting-guide.md)**. Diagnostic priority: incidents → runtime variables → caseplan.json correlation → traces (last resort).
+
+**Diagnose → fix → re-run loop.** After each diagnostic pass, classify the root cause and act:
+
+1. **Fixable in `caseplan.json`** (wrong binding, missing condition, malformed expression, incorrect input value): apply the targeted fix via the matching plugin's `impl-json.md`, re-run `uip maestro case validate`, then re-run Step 14 debug.
+2. **Fixable outside `caseplan.json`** (missing/expired connection, unregistered task type, missing Orchestrator asset, permissions): halt agent edits. Report exact resource + remediation steps to the user via **AskUserQuestion** with options — `Resource fixed, re-run debug`, `Abort`.
+3. **Inconclusive** (no actionable cause): proceed to next round per retry policy.
+
+**Retry policy.** Up to 3 troubleshoot → fix → debug rounds per failed run. Each round must add new context (different element ID, broader scope, fallback command) or apply a different fix — do not repeat identical commands or re-apply the same fix. Track round count.
+
+After the 3rd inconclusive round (or 3rd debug failure post-fix), halt and ask the user with **AskUserQuestion**. Report: instance ID, folder key, incident IDs/messages, faulting element ID, variable snapshot, what was tried each round. Options — `Provide additional context` (user supplies hints; run one more targeted round), `Pause for manual investigation`, `Abort`. Do not propose `caseplan.json` edits without confirmed cause.
+
 ## Step 15 — Optional: Publish to Studio Web
 
 **Default publish target.** Uploads the case to Studio Web for visualization and editing.

skills/uipath-maestro-case/references/troubleshooting-guide.md

@@ -0,0 +1,119 @@
+# Troubleshooting Failed Cases
+
+Diagnostic workflow for failed debug runs and deployed case process runs. All commands require `uip login`.
+
+> **`--folder-key` is required for `incident get`.** Most `instance` subcommands accept `--folder-key <FOLDER_KEY>` and auto-detect from the authenticated folder if omitted, but `incident get` requires it explicitly. Get the folder key from `uip orchestrator folder list --output json` or from the job/process context.
+
+## Diagnostic priority
+
+Investigate in this order — each step adds context, stop when you have enough to diagnose the root cause:
+
+1. Incidents (error message + faulting element)
+2. Runtime variables (data state at failure)
+3. Case definition correlation (map element to `caseplan.json` node)
+4. Traces (last resort — verbose full timeline)
+
+## Step 1 — Get the instance ID
+
+The debug output (`Data.instanceId`) or `job status` response contains the instance ID. If you only have a job key:
+
+```bash
+uip maestro case job status <JOB_KEY> --output json
+```
+
+Parse the instance ID and folder key from the response.
+
+> **No instance ID / `job status` fails →** halt. Report job key to user; downstream steps need the instance ID.
+
+## Step 2 — Fetch incidents
+
+Failed cases always have an incident. Start here — incidents give you the error category, message, and the faulting element.
+
+```bash
+uip maestro case instance incidents <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Drill into a specific incident for full detail:
+
+```bash
+uip maestro case incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+To get a cross-process incident overview:
+
+```bash
+uip maestro case incident summary --output json
+```
+
+For all incidents on a specific case process:
+
+```bash
+uip maestro case processes incidents <PROCESS_KEY> --folder-key <FOLDER_KEY> --output json
+```
+
+> **Empty incidents →** skip to Step 3. **Invalid instance ID error →** recheck Step 1 output.
+
+## Step 3 — Fetch runtime variable state
+
+Get the variable values at the time of failure to understand what data each stage/task was working with:
+
+```bash
+uip maestro case instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Scope to a specific element (stage or task):
+
+```bash
+uip maestro case instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json
+```
+
+> **Empty variables →** skip to Step 4.
+
+## Step 4 — Correlate with the case definition
+
+Use the incident's faulting element ID and the variable state to locate the failure point in `caseplan.json`. Map the element ID to the corresponding stage, task, edges etc., check its `data.inputs[]`, upstream edges, and the variable values flowing into it.
+
+If the local `caseplan.json` may differ from what was deployed, fetch the deployed case definition:
+
+```bash
+uip maestro case instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+> **`instance asset` fails →** fall back to local `caseplan.json`.
+
+Additional instance inspection commands:
+
+```bash
+uip maestro case instance element-executions <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json  # per-element execution details
+uip maestro case instance cursors <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json             # current execution cursor positions
+```
+
+## Step 5 — Traces (last resort)
+
+Traces are verbose but contain the full execution timeline. Use them only when incidents and variables are insufficient:
+
+```bash
+uip maestro case job traces <JOB_KEY> --output json
+uip maestro case job traces <JOB_KEY> --pretty                  # human-readable form
+```
+
+> **Always use CLI commands for troubleshooting — never call the underlying APIs directly.**
+
+## Stop conditions
+
+1. **Stop early on root cause.** Once a step yields actionable cause (error + faulting element + variable state), stop. Skip remaining steps.
+2. **Empty result → next step.** If a step returns empty/missing data, move to the next step. Do not retry the same command.
+3. **One retry on transient failure** (auth, network). Second failure: halt that step, continue.
+4. **Max one full pass through Steps 1–5.** No looping.
+5. **Escalate to user** if Steps 1–5 yield no root cause, or all paths blocked. Report: instance ID, folder key, incident IDs/messages, faulting element ID, variable snapshot. Do not propose `caseplan.json` edits without confirmed cause.
+
+## CLI command reference
+
+For full flag tables and all subcommands, see [case-commands.md](case-commands.md):
+
+- `uip maestro case instance` — list/get/incidents/variables/asset/cursors/element-executions and lifecycle (pause/resume/cancel/retry/migrate/goto)
+- `uip maestro case incident` — `summary`, `get`
+- `uip maestro case processes incidents <PROCESS_KEY>` — all incidents on a process
+- `uip maestro case job` — `status`, `traces`
+
+Append `--output json` to any command whose output you parse.