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.

No fabrication. Data unavailable → say so. Never invent data or substitute unrelated data.
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.
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.
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.
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).
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.
Live ≠ historical. Current snapshots (machine status, licenses, connections) cannot prove what happened during incidents older than 24h — context only.
Symptom ≠ cause. A matching error string confirms the playbook match, not the cause. The §6 checklist gates every conclusion.
No inference from undocumented fields. Behavior not in a playbook or docsai result → flag as unverified, don't guess.
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 cloud/tenant state with no local file (Orchestrator config, Integration Service connection, Data Fabric, LLM Gateway) is recommendation-only — print the exact
```
uip …
```
command or UI path; never delegate, never self-apply. Diagnostic commands stay autonomous: reads, and playbook-prescribed idempotent re-validations whose purpose is evidence (e.g. a same-values
```
update
```
re-probe). A request for steps or a script is a deliverable, not execution approval — author it, do not run it. On decline, non-answer, unavailable
```
AskUserQuestion
```
, no available delegate, or a delegation that fails: present the proposed fix as text and STOP — a missing/failed approval or a failed delegation is NEVER permission to edit the artifact yourself.
No ad-hoc code execution. Playbook-provided diagnostic snippets are recommendations for the user unless the playbook says to run them. Shell for file I/O and uip is fine.

Tools: uip CLI (json by default in non-interactive mode). Documentation search:

uip docsai ask "<question>" --source docs

(product docs) or

--source technical_solution_articles

(support KB — known bugs, workarounds).

State:

.local/investigations/raw/

(full CLI responses — create at start) and

.local/investigations/notes.md

(running log: anchor, signals, playbook matches, branch decisions with rejecting data, checklist verdicts, escalation record). No other state files.

Progress: track phases with TaskCreate/TaskUpdate, subjects tailored to the user's problem.

2. Anchor & primary evidence

Classify (system, entity) from the user's message. Cross-check against
```
references/summary.md
```
domains.
Branch on anchor presence:
- Anchored — user named a concrete locator (id/key, process/package/queue/folder name, instance/incident id, specific error code/message), or the working directory contains a recognisable UiPath project at top level (
```
project.json
```
  ,
```
agent.json
```
  ,
```
caseplan.json
```
  ). Run the first locator command documented in the system's
```
investigation_guide.md
```
  ; if the system has no guide, proceed with the user-supplied signals to §3–§4 — the matched playbook's
```
## Investigation
```
  supplies the commands.
- No anchor — ask via
```
AskUserQuestion
```
  , offering plausible anchor candidates. Do NOT broad-scan, do NOT fetch a placeholder entity, do NOT enumerate folders/queues hoping to find the right one. A bounded locate pass only if the user explicitly authorizes a scan — then confirm the candidate with them.
Entity-instance selection when a query yields multiple candidates (several faulted jobs, incidents): filter by the user-named or directory-implied anchor and take the most recent match; if candidates span multiple plausible anchors, ask — do not default; fall back to most-recent-overall only with user-authorized scan.
Fetch the primary entity and its error surface per the domain's
```
investigation_guide.md
```
when the domain has one (always also read
```
references/investigation_guide.md
```
for generic Data Correlation and Output Capture rules). Gather only what routes: entity headline, error message, exception class, error code, activity/package namespace from error logs. Deeper data (full traces, healing data, secondary entities, pings) waits until a playbook's
```
## Investigation
```
asks for it.

3. Extract signals

From the raw responses, record in notes.md one line per observed fact: exception class (FQN + leaf), friendly message / resource key, error code, HTTP status, faulting activity + owning package namespace, entity states, cross-product entity keys, package versions. Field locations per signal kind: see the cheatsheet in

references/investigation_guide.md

§ Signal-Extraction Cheatsheet.

Unwrap wrappers at extraction time.

System.AggregateException

and "One or more errors occurred" are async wrappers — the inner exception is the routable signal. Extract inner exception class, message, and error code before routing. Same for

--->

-chained inner exceptions in stacks.

Localized error text. Host-side messages (.NET framework, Office/COM) localize with the robot's system language; playbooks store canonical English. Route on language-invariant signals first — exception class/FQN, error codes, resource keys, HTTP status, API state enum values (these never localize). If a message fragment is non-English, grep the playbooks with its canonical English wording (translate before grepping) and record the original text plus locale in notes.md.

4. Route

Grep the playbook corpus for each extracted signal — fixed-string, filenames only (

grep -rlF "<signal>" references/ --include="*.md"

): leaf exception class, error code, message fragments, resource keys. Signals are verbatim — a shorter fragment beats a guessed-case variant. Prefer hits under

*/playbooks/

; never read directories wholesale — open only the hits'

## Context

sections to check fit.

One dominant playbook — most distinct signal hits; ties break by reading each hit's
```
## Context
```
and keeping the one whose preconditions fit the evidence; honor a playbook's explicit redirects to sibling playbooks. → Load ONLY that playbook + its domain's
```
investigation_guide.md
```
(if the domain has one). Go to §5.
Cross-domain signal — evidence carries a key/ID/exception belonging to another product (e.g., an Excel fault wrapping an Integration Service connection error, an Orchestrator job spawned by a Maestro instance). → Follow the chain one hop: fetch the linked entity's error surface, extract its signals, re-grep. The upstream playbook drives the resolution; the downstream domain contributes a propagation fix (
```
references/presenting.md
```
). Deeper than one hop → escalate.
Fault signal but no grep hit — map the faulting activity/exception namespace to its owning domain (
```
references/summary.md
```
) and check that domain's
```
summary.md
```
for a family playbook covering the activity. One dominant family playbook → proceed to §5 with it. Still nothing → escalate.
No match, or an escalation trigger (§7) fires → load
```
references/escalation.md
```
. For silent failures (no fault signal anywhere: job Successful but wrong output, hang, stuck state), enter via the no-signature routing table in
```
references/summary.md
```
.

5. Walk the playbook

Read the playbook's
```
## Context
```
fully; confirm its signature actually fits the evidence (a contradicted core precondition = wrong playbook → back to §4 with that match excluded, recorded in notes.md).
Execute its
```
## Investigation
```
steps in decision-tree order; stop at the first matching branch. Record in notes.md the datum that rejects each rejected branch.
Ordering rules: most-specific branch first; run elimination checks, not just confirmation (fetch what would DISPROVE the branch); never conclude on a propagation/persistence/state-transition pattern while an upstream "why did that state occur" is unanswered — trace one hop upstream first.
Source-required playbooks (evidence lives only in workflow source, e.g.
```
VerifyOptions
```
, selectors,
```
project.json
```
pins): CHECK THE WORKING DIRECTORY TOP LEVEL FIRST — one listing; if it contains the project (
```
project.json
```
+ the workflow named in the activity stack), use it without asking. A playbook-named file not at its standalone path may sit in the other layout — resolve both (solution wrapper at the working-directory root / one level up from the named project dir) per generic guide § Locating Project Source & Resource Files before treating it as missing; absence from one layout is not absence. Only if neither layout resolves, ask for the project path via
```
AskUserQuestion
```
— one question naming the files needed. This precedence overrides any playbook wording that says to ask first. Extract the verbatim attribute values the playbook lists; do not paraphrase.
For large result sets, summarize at write-time — group by type, count patterns, extract samples. Never slice raw responses with arbitrary limits.

6. Verification checklist — mandatory before presenting

Evidence is decisive. The conclusion is the cause the correlated evidence singles out — follow it. A plausible-but-unsupported alternative (a source-reading theory, a prior, the cause that is "common in production") NEVER overrides a documented cause the evidence supports; strongest correlated evidence wins over narrative plausibility. When the evidence does NOT single out one cause, do not pick — take the insufficient-evidence path below.

Write the answers in notes.md; do not skip items, do not present without them:

Cause named: quote ONE item verbatim from the playbook's "What can cause it" list — not a category, not a vague generalization.
Evidence pinned: cite ≥1 datum (raw file + field) that singles out this cause from each sibling cause in the same list. Symptom-level data fitting several causes is not enough.
Runtime evidence: for runtime failures, ≥1 cited datum from runtime/platform data (logs, job records, instance state, incidents) that passes correlation. Design-time evidence alone (source files, manifests) proves a defect exists, not that it caused this failure. A design-time-only root cause is BLOCKED while any documented runtime command for the entity remains untried — a "runtime unavailable/empty" verdict is valid only after the documented log/incident command was run in its canonical form (e.g.
```
or jobs logs <key> --output json
```
,
```
maestro <type> instance incidents <id>
```
) and returned empty. Every runtime query empty while the user reports active failures = CONTRADICTION — wrong scope; re-verify or ask, never conclude. If the contradiction persists and the user cannot be asked, present the contradiction itself as the finding (runtime evidence unreachable — root cause unconfirmed) — never re-attribute the failure to a design-time observation.
Resolution aligned: the fix is the playbook's
```
## Resolution
```
branch keyed to that exact cause.
Causal precedence: list every event the conclusion treats as given and answer "why did that occur?" — each answered by evidence, explained by the named cause, or explicitly out of scope. An upstream event may be ruled out of scope ONLY if no documented command (a matched playbook's
```
## Investigation
```
or an investigation guide) can retrieve the record that explains it; if such a command exists, running it is mandatory before concluding. A persistence/state-transition story (cancelled, stopped, orphaned, disconnected, timed-out) presupposes an upstream condition and is never the root cause while the record explaining it is reachable and unqueried; unexplained upstream → not root cause.
Fix scope: every proposed fix traces to the confirmed cause. A property or code path the failing run never evaluated cannot be asserted as a defect from source reading alone — and a defect claim that rests on how the platform parses or evaluates source syntax (expression bindings, escaping, argument direction) is unverified until confirmed against a playbook or documentation. Surface such suspicions as clearly-labeled unverified observations OUTSIDE the fix list — labeling one a "separate observation" while still listing it as a fix or offering to apply it violates this rule. The same gate applies to solutions: a fix must not presuppose infrastructure or mechanisms absent from the evidence (e.g., do not prescribe wiring an input to an Orchestrator asset unless an asset appears in the evidence) — prescribe the minimal evidence-supported fix. A fix option may name a real-world/production pattern in prose or context, but must NOT prescribe adding an activity, component, connection, asset, or endpoint that is absent from the workflow/evidence — not even as a labeled alternative or fix step. The presented fix MUST match this item's own scope verdict: if the fix touches only property X with no other activities implicated, it cannot introduce a new activity.

The checklist gates the output. Before presenting, re-read your six answers and confirm the final Root Cause and every Fix step are consistent with ALL of them — the cause is quoted verbatim from the playbook's "What can cause it" list (item 1), and no fix exceeds the item-6 scope. A conclusion or fix that contradicts any item is NOT presentable; resolve the contradiction first (re-fetch, re-scope, or downgrade to unconfirmed).

Any check fails → ONE targeted re-fetch for the missing datum. Still failing → insufficient evidence: do NOT pick a cause. Name the surviving candidate causes and, for each, the discriminating signal that would separate them, then:

Fetch the discriminator with a documented command if one exists (the playbook's
```
## Investigation
```
usually names it) → re-evaluate.
Ask the user when the discriminator needs data you cannot fetch: present the candidate causes and, for each, the signal that would confirm it, and call
```
AskUserQuestion
```
to supply or confirm that signal — then continue the investigation from their answer. Do not guess in their place.
Diagnostic-recommendation terminal (only when the user cannot be asked): if the playbook provides a discriminating diagnostic (e.g., a byte-compare snippet), present at reduced confidence with that diagnostic as the primary deliverable — never silently pick a branch.
Otherwise, or if a §7 trigger fires → escalate.

7. Escalation triggers

Load

references/escalation.md

when ANY of:

No playbook grep match — silent failure, hang, wrong results, nothing greppable.
≥2 co-equal matches with distinct, independent signatures (different activities/error codes, neither upstream of the other).
Cross-domain chain deeper than one hop, or the one-hop follow contradicts the original match.
Decision tree exhausted — every branch rejected, or a discriminator stays inconclusive after its named evidence is gathered.
Checklist fails after the re-fetch and no diagnostic-recommendation terminal applies.
Evidence or new user data contradicts the matched playbook's core precondition.

Escalation = 2–4 parallel read-only probe subagents (one per candidate playbook + one "origin is upstream/elsewhere") + your adjudication + a conditional fresh-eyes verifier. Protocol, prompt templates, and spawn budget:

references/escalation.md

. No subagent-spawning tool in this harness → same protocol, probes executed serially in this context (

references/escalation.md

§ Serial fallback).

8. Present

Load

references/presenting.md

and follow it: fixes assembled for the root-cause domain and every propagation domain, every step source-cited, entity display names from raw data, the investigation summary table, and interactive resolutions (Healing Agent apply-flow) executed under the §1 approval gate.

9. New data from the user

New data mid-investigation (error messages, job IDs, logs) → re-run §2–§4 on it. If the new signals contradict the current match, that is trigger 6. Never patch new data into a concluded narrative.

10. Completion

After presenting and finishing any interactive actions: offer follow-up help and offer to delete or preserve

.local/investigations/

. If no root cause was found, offer via

AskUserQuestion

: provide more data (re-anchor) or open a UiPath support ticket with the evidence gathered.

uipath-troubleshoot

NPX Install

Tags

SKILL.md Content