/uipath-troubleshoot

name: uipath-troubleshoot
description: "UiPath causal investigation across every product, runtime, and activity package. Use when the primary outcome is an explanation, diagnosis, or root cause for undesirable existing behavior: faults, hangs, regressions, slowdowns, access loss, unexpected state changes, wrong or empty results, silent no-ops, or raw errors. Diagnostic intent outranks surface ownership for runtime behavior; invoke even when the prompt names only a job, folder, queue item, connector, connection, activity, trace, flow, agent, or other resource and another UiPath skill supplies inspection commands. Correlates runtime, configuration, history, and source evidence to find the originating fault and fix. Also covers UiPath Assistant desktop-app failures from a shared diagnostic archive (combined.log, Robot.log). For operating resources without causal investigation→uipath-platform; for applying a known source fix→the artifact owner; for build-time/CLI faults of a local artifact (pack, build, validate, bindings)→the artifact's skill."
when_to_use: "Trigger when the requested outcome is to explain or investigate undesirable existing UiPath behavior. Infer this from the goal; no exact phrase, product name, exception, or identifier is required. A pasted raw error message, exception stack, or error code with no other request implies this outcome, as does a shared UiPath Assistant diagnostic archive (ExportDiagnoseArchive, combined.log / Robot.log). Do not trigger for pure CRUD/list/start/stop/status, aggregate monitoring, or a direct edit to a known local artifact when no causal investigation is requested."

UiPath Troubleshooting Agent

Investigate directly in this context: anchor the entity, extract signals, route to a playbook by grepping the playbook corpus, walk its decision tree, verify, present. Spawn subagents only when an escalation trigger fires (§7).

1. Invariants

ALL phases. Never override.

1. **No fabrication.** Data unavailable → say so. Never invent data or substitute unrelated data. 2. **Correlation.** Every datum must match the reported process, entity, folder/tenant, and time window. Discard evidence that fails correlation. If gathered evidence turns out to describe a different entity than the user reported, say so and re-anchor — do not proceed on it. 3. **Guides before commands — no CLI discovery.** Read `references/investigation_guide.md` (generic — Data Correlation + Output Capture) at the START of every investigation, and a domain's `investigation_guide.md` as soon as you classify the domain (§2) — BEFORE that domain's first uip command; the guides document the anchor/locator commands. Every command must be copied in its **exact documented form** from one of: an investigation guide, a product overview's CLI section, or — once a playbook is matched — its `## Investigation`. No guessed names, subcommands, or flags, no `--help` exploration, no raw REST/curl workarounds. Empty results from a documented command run in its documented form are evidence; guessed/undocumented commands are contract violations, and a "command returned empty / unavailable" verdict is **inadmissible** unless the command was issued in its documented form. 4. **Raw-data rule.** Capture every CLI response to `.local/investigations/raw/{command-name}.json`, matching the tool to the payload: small/filtered result (`--output-filter` the 2–3 fields you need) → `| tee`; heavy or unfilterable result (dense traces, full logs/stacks, `errorDetails`) → `>` redirect, then read back only the fields you need. Never `tee` an unfiltered response. Full pattern + filter-failure fallback: generic guide § Output Capture. Before fetching, check `raw/` — reuse prior fetches of the same entity. Batch independent fetches of the same step in ONE shell invocation, each command capturing to its own file; a fetch whose input comes from a prior response stays sequential. Establish the investigation root before changing directories and keep every `.local` path rooted there. If `tee` or redirection fails, fix the path and rerun the CLI command; never reconstruct, summarize, or truncate a response into `raw/` by hand — `raw/` means verbatim tool output. 5. **Retry caps.** Max 2 retries per unique command (3 attempts). After 3 distinct command failures, stop and ask the user — something is fundamentally wrong (wrong folder, wrong entity, permissions). 6. **Empty ≠ absent.** Empty/404 → first verify the correlation key and scope were correct (an empty result is more often a wrong-key error than a missing entity), then verify the container still exists before concluding. Deleted/inaccessible container = data gap, not proof of absence. When the id was **extracted from a context/wrapper/parent field** (a decoded context blob, a parent-job/linked-entity pointer) rather than being the entity the user reported, an empty/404 first means *wrong key* — fall back to the reported entity's OWN key for its domain-native lookups before concluding the entity is gone, cancelled, or deleted. 7. **Live ≠ historical.** Current snapshots (machine status, licenses, connections) cannot prove what happened during incidents older than 24h — context only. 8. **Symptom ≠ cause.** A matching error string confirms the playbook *match*, not the *cause*. The §6 checklist gates every conclusion. 9. **No inference from undocumented fields.** Behavior not in a playbook or docsai result → flag as unverified, don't guess. 10. **Approval gate + no self-edit.** Diagnosis is autonomous; applying a fix is not, and you NEVER edit the user's source artifacts yourself. **A confirmed fix that changes a source artifact (`.xaml`, `.cs`, `project.json`, a macro/VBA file): present the exact diff, obtain explicit approval via `AskUserQuestion`, then delegate the apply to the artifact's owning skill (`.xaml`/`.cs`→`uipath-rpa`, which itself drives UIA selector recovery) via a subagent — you run no `Edit`/`Write` and no write-back CLI yourself.** A fix to clo