@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/selector-failure-healing-disabled.md

@@ -0,0 +1,55 @@
+---
+confidence: high
+---
+
+# Selector Failure — Healing Agent Disabled
+
+## Context
+
+A UI automation activity failed because its selector didn't match any element in the live UI tree. Healing Agent was not enabled on the process, so no automated recovery data is available.
+
+What this looks like:
+- SelectorNotFoundException, UiElementNotFoundException, ElementNotInteractableException, or NodeNotFoundException during activity execution
+- AutopilotForRobots shows Enabled: false or HealingEnabled: false (or field absent)
+
+What can cause it:
+- Target application UI changed (redesign, update, dynamic content)
+- Element attribute became dynamic (index shifted, name changed per session)
+- Element hidden behind an overlay, popup, or dialog
+- Wrong application window targeted
+- **Wrong-page scope (authoring defect)** — the parent `NApplicationCard` / `Attach Browser` / scope wrapper's `TargetApp.Url` (or `TargetApp.Selector` title) mismatches the child Click's expected page. Common subcase: `AttachMode=ByInstance` + a permissive title selector latch the card onto a pre-existing tab on the wrong page, and the card contains no navigation activity before the click. The selector itself is fine — it just runs against the wrong page.
+
+## Investigation
+
+1. Confirm UIAutomation failure via trace spans (activity types: `UiPath.UIAutomationNext.*`, `UiPath.UIAutomation.*`, `UiPath.Core.Activities.Click`, etc.)
+2. If trace unavailable, infer from exception type (SelectorNotFoundException is definitively UI)
+3. TimeoutException is ambiguous — only classify as UI if trace confirms UI activity type
+4. **Decide whether wrong-page scope is plausible from CLI evidence alone.** Strong signal: the exception's closest-match list contains elements from a clearly different page than the failing activity targets — different language locale, different site section, different element family. Weak signal: closest matches are similar to the target. **Eliminating signal:** if the exception's stack or job traces show that other activities in the same parent scope wrapper executed successfully before the failing one, wrong-page-scope is **ruled out** — the scope is attached to the right page; only the failing element is the problem.
+5. **If wrong-page scope is plausible, ask the user for the project source path.** Use `AskUserQuestion` to request the path to the project (folder containing the workflow files). Explain that the parent scope wrapper's configuration needs to be inspected against the failing activity's target to confirm or eliminate the wrong-page-scope hypothesis. **Do not glob, search, or assume a project path.** If the user declines or has no path: skip step 6 and mark the wrong-page-scope hypothesis as unverified.
+6. **Only if the user supplied a project path**, inspect the parent scope wrapper (`NApplicationCard`, `Attach Browser`, `Open Application`, etc.):
+   - Read the workflow file named in the exception's activity stack from the user-supplied path
+   - Find the failing activity inside its parent scope wrapper
+   - Extract `TargetApp.Url`, `TargetApp.Selector`, and `AttachMode` from the parent scope
+   - Extract the failing activity's `Target.BrowserURL` (or `ScopeSelectorArgument`)
+   - Count navigation activities (`NGoToUrl`, `NavigateBrowser`, `OpenBrowser`, `NGoToUrlX`) inside the scope wrapper before the failing activity
+   - **Wrong-page-scope is confirmed** when ALL of these hold: parent `TargetApp.Url` ≠ child `Target.BrowserURL`, navigation activity count = 0, and the closest-match list confirms a different page
+7. **Only conclude "stale selector / UI changed"** when wrong-page scope has been ruled out (or marked unverified because no source was supplied) AND the closest matches contain elements with similar `aaname`/`class` from the intended page
+
+## Resolution
+
+Branch by what the investigation identified:
+
+**If wrong-page scope (authoring defect):**
+- Insert a navigation activity (`Go To URL` / `Navigate Browser` / `NGoToUrl`) inside the parent scope before the failing activity, targeting the click's expected URL — OR
+- Repoint the parent scope's `TargetApp.Url` to the click's expected page AND tighten `TargetApp.Selector` (title) to match the destination page — OR
+- Change `AttachMode` from `ByInstance` to one that opens/navigates rather than only attaching to a pre-existing window
+- Re-record the click on the page the scope actually attaches to, if the scope page is the intended one
+
+**If stale selector / UI changed:**
+- Re-indicate the element in Studio and update the Object Repository descriptor
+- Prefer stable attributes (role, automationId, aria-label) over numeric/generated suffixes
+- Add a FuzzySelector and/or anchor
+
+**Always:**
+- Enable Healing Agent on the process so future drift is captured automatically.
+- Note: Enabling HA does not fix wrong-page-scope defects — HA recovers selectors against the live page, but if the live page is the wrong page, HA has no correct target to recover toward.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/selector-failure-healing-fix.md

@@ -0,0 +1,45 @@
+---
+confidence: high
+---
+
+# Selector Failure — Healing Agent Recovery Data Available
+
+## Context
+
+A UI automation activity failed because its selector didn't match any element in the live UI tree. Healing Agent was enabled and produced recovery data — either a deterministic fix in `healing-fixes.json` (self-healing path) or an `InferredRecoveryInfo` entry inside `uia/*.json` (recommendation-only path).
+
+What this looks like:
+- `SelectorNotFoundException`, `UiElementNotFoundException`, `ElementNotInteractableException`, or `NodeNotFoundException` during activity execution
+- HA was enabled on the run (`AutopilotForRobots.Enabled=true`, `HealingEnabled=true`)
+- One of the following recovery artifacts exists for the faulted activity:
+  - `healing-fixes.json` with a matching entry (self-healing path — proven or attempted at runtime), OR
+  - `uia/*.json` with a non-null `InferredRecoveryInfo` / `RecoveryInfo` containing a recovered target (recommendation-only path when `HealingAgentContext.OrchestratorEnableHeal=false`)
+
+What can cause it:
+- Target application UI changed (redesign, update, dynamic content)
+- Element attribute became dynamic (index shifted, name changed per session)
+- Authoring-time selector mistake against a stable element (typo, wrong attribute value, copy-paste error) — the live element is unchanged but the workflow's selector never matched
+- Element temporarily obscured by a popup or overlapping window (HA may emit a `dismiss-popup` fix instead of `update-target`)
+
+This playbook applies whenever HA recovery data is present for the failing activity, regardless of which specific cause above produced the failure. The cause label affects the user-facing narrative; the **remediation procedure (present HA's recommendation, ask whether to apply it) is the same for all of them** and is the authoritative resolution path even when the cause is later refined (e.g., depth-verifier identifies an authoring typo rather than UI drift).
+
+## Investigation
+
+1. Identify the recovery channel:
+   - **Self-healing path** — `healing-fixes.json` exists at the job cache root. Match an entry by `ActivityRefId` (preferred) or `activityName` + `workflowFile`.
+   - **Recommendation-only path** — `healing-fixes.json` is absent but `uia/*.json` contains `InferredRecoveryInfo` or `RecoveryInfo` with `RecoveredTarget`/`RecoveredSecondaryTarget`. `HealingAgentContext.OrchestratorEnableHeal=false` is the signature of this mode.
+2. **Extract concrete selector strings** from the recovery data so they can be shown to the user. Do NOT summarize them away — the actual XML strings are required by the resolution procedure:
+   - **Failed selector** — `Content.FailedResolvedTarget.PartialSelector` (and `FuzzyPartialSelector` if present) from the matching `uia/*.json`.
+   - **Recovered selector** — for self-healing: `enhancedTarget` / `clickTarget` from the `healing-fixes.json` entry. For recommendation-only: locate the detection in `Content.AnalysisResult[0].AnalysisInformation[*].Detections[*]` whose `Id` matches `InferredRecoveryInfo.RecoveredTarget.DetectionId` (or, when no DetectionId is set, take the detection from the strategy with the highest-confidence consensus per `interpretations/healing-agent-data.md` § "Detections Without Recovery Entries"). Read its `EnhancedTargetDto.PartialSelector` and `EnhancedTargetDto.FuzzyPartialSelector` (fall back to `InferredTargetDto.*` if `EnhancedTargetDto` is empty).
+3. Compare failed vs recommended selector and note which attributes changed (text, index, role, ancestry, etc.).
+4. Record the recovery channel, the detection's `InferMethod` / confidence score, and whether self-healing actually applied the fix at runtime (`RecoverySuccessful`). These determine the warning attached to the apply-fix prompt.
+
+Persist the exact failed and recovered selector strings to the evidence file for this hypothesis (e.g., as `failed_selector_xml`, `recovered_partial_selector_xml`, `recovered_fuzzy_partial_selector_xml`). The orchestrator's Resolution phase will read them back to drive the `AskUserQuestion` apply-fix flow — they MUST be present verbatim, not paraphrased.
+
+## Resolution
+
+Follow the fix-application procedures in [interpretations/healing-agent-data.md](../interpretations/healing-agent-data.md) (section "Applying HA Fixes" and "Applying Fixes — MUST Ask the User"):
+- For `update-target` (self-healing) or `InferredRecoveryInfo.RecoveredTarget` (recommendation-only): use `uia-improve-selector` skill if available, otherwise direct XAML edit. When the data is `InferredRecoveryInfo` or `RecoverySuccessful: false`, attach the runtime-not-validated warning to the apply-fix prompt.
+- For `dismiss-popup` / `RecoveredExternally`: create a Click activity before the failing activity, validate the workflow compiles.
+
+This resolution path is **interactive** — it requires `AskUserQuestion` to be called by the orchestrator at the end of the troubleshooting to (a) print the Failed / Recovered Partial / Recovered Fuzzy selectors as plain text, (b) ask the user whether to apply the fix and which selector variant. The presenter must emit a `## Post-presentation actions` block declaring this interactive step; the orchestrator must execute it before closing the investigation. Do not collapse this into a generic "fix the selector" recommendation — the recovered selector text and the apply-fix prompt are part of the documented resolution.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/selector-failure-manual.md

@@ -0,0 +1,44 @@
+---
+confidence: medium
+---
+
+# Selector Failure — Manual Investigation
+
+## Context
+
+A UI automation activity failed because its selector didn't match any element in the live UI tree. Either Healing Agent was enabled but didn't produce fixes, or source code is available for manual selector analysis.
+
+What this looks like:
+- SelectorNotFoundException, UiElementNotFoundException, ElementNotInteractableException, or NodeNotFoundException during activity execution
+- Healing Agent data exists but no fix was produced, OR source code is available for direct analysis
+
+What can cause it:
+- Target application UI changed (redesign, update, dynamic content)
+- Element attribute became dynamic (index shifted, name changed per session)
+- Element hidden behind an overlay, popup, or dialog
+- Timing issue — element not loaded yet when activity executed
+- Wrong application window targeted
+- Scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`) attached to a different page/window than the selector expects — see [scope-container-wrong-page.md](./scope-container-wrong-page.md)
+
+What to look for:
+- Get the faulted activity name and selector from job traces or XAML source
+- Check if the target application changed recently (version update, UI redesign)
+- Check selector attributes — fragile selectors use title/name, robust selectors use automationId/className
+- If HA data exists but no fix was produced: check eligibility and confidence threshold
+
+## Investigation
+
+1. **Read the enclosing scope container** (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`, `Attach Browser`, `Attach Window`) from the XAML — record `AttachMode`, `OpenMode` (defaults to `IfNotOpen` when absent), and `TargetApp.{Selector,Url}`. If the scope is permissive enough to attach to an unintended tab/window (`AttachMode=ByInstance` + `OpenMode=IfNotOpen` + loose `TargetApp.Selector`, or `TargetApp.Url` not matching the inner selector's intended page), the defect is the scope, not the selector — switch to [scope-container-wrong-page.md](./scope-container-wrong-page.md) before proceeding.
+2. Locate the faulted activity in XAML by `IdRef`
+3. Extract the selector from the XAML (decode XML encoding: `&amp;` -> `&`, `&lt;` -> `<`, etc.)
+4. Analyze the selector: which attributes are used? Are any dynamic (idx, tableRow, etc.)?
+5. Check selector attributes — fragile selectors use title/name, robust selectors use automationId/className
+6. Check if the target application has changed recently
+7. Compare against Object Repository if available
+8. If HA data exists but no fix was produced: check eligibility and confidence threshold
+
+## Resolution
+
+- Update the selector to use more stable attributes (aaname, automationid, role) instead of volatile ones (idx, tableCol, tableRow)
+- Add wildcard matching for dynamic portions: `name='Invoice*'` instead of `name='Invoice_20250319'`
+- Consider adding a Check App State activity before the failing activity to wait for the element

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/timeout-issue.md

@@ -0,0 +1,35 @@
+---
+confidence: low
+---
+
+# Timeout Issue
+
+## Context
+
+A UI automation activity exceeded its timeout waiting for an element or application state. The default timeout is typically 30 seconds.
+
+TimeoutException is ambiguous — it could be a UI timeout (Check App State, element wait) or a non-UI timeout (HTTP request, queue transaction). Confirm the faulted activity is a UI automation type before following this playbook.
+
+What this looks like:
+- Activity waited the full timeout duration and threw TimeoutException
+- The target element either never appeared or took too long to become interactable
+
+What can cause it:
+- Target element genuinely doesn't exist (page didn't load, navigation failed, wrong page)
+- Application is slower than usual (server-side delay)
+- Element exists but appears after the timeout window (timing gap)
+- Robot session is locked or in a disconnected RDP session
+- Picture-in-Picture (PiP) mode has different element visibility rules
+
+What to look for:
+- Is the faulted activity a UI automation type? If not, this playbook doesn't apply
+- Is the activity duration close to the configured timeout? (within 1-2 seconds = genuine timeout)
+- Is the issue intermittent (works sometimes, fails sometimes)?
+- Is the robot session locked or disconnected?
+
+## Resolution
+
+- If application is genuinely slower: increase the timeout value in the activity properties
+- If wrong page is displayed: fix the upstream navigation logic
+- If timing gap: add a Check App State or Element Exists activity before the failing activity
+- Do NOT just increase timeout blindly — find out why the element is delayed

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/presentation.md

@@ -0,0 +1,5 @@
+# UI Automation Presentation Rules
+
+- **Activities** — use the display name (e.g., "Click", "Type Into", "Get Text"), not the fully qualified class name (e.g., `UiPath.UIAutomationNext.Activities.NClick`)
+- **Selectors** — show the human-readable target description (e.g., "Click 'Submit' button") alongside the selector XML when relevant. Do not show raw selector XML as the primary identifier.
+- **Elements** — describe by what the user would see (e.g., "the 'Collaboration' link"), not by selector attributes alone

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/summary.md

@@ -0,0 +1,14 @@
+# UI Automation Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for UI Automation investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Selector Failure — Healing Fix Available | High | Selector mismatch with Healing Agent fix in `healing-fixes.json` | [selector-failure-healing-fix.md](./playbooks/selector-failure-healing-fix.md) |
+| Selector Failure — Healing Disabled | High | Selector mismatch with Healing Agent not enabled on the process | [selector-failure-healing-disabled.md](./playbooks/selector-failure-healing-disabled.md) |
+| Selector Failure — Manual Investigation | Medium | Selector mismatch requiring manual analysis (HA produced no fix or source code available) | [selector-failure-manual.md](./playbooks/selector-failure-manual.md) |
+| Selector Failure — Scope Container Attached to Wrong Page/Window | Medium | Scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`) attached to a different page/window than the inner selector expects; the selector itself is correct for its intended page | [scope-container-wrong-page.md](./playbooks/scope-container-wrong-page.md) |
+| Disabled Element — AlterIfDisabled Not Enabled | High | `UiNodeDisabledElementException` from any UIAutomationNext interaction activity (NClick, NTypeInto, NSetText, NCheck, NSelectItem, NSAPClickPictureOnScreen) where the target was found but disabled and `AlterIfDisabled` was not set | [disabled-element.md](./playbooks/disabled-element.md) |
+| Timeout Issue | Low | UI automation activity exceeded its timeout waiting for an element or application state | [timeout-issue.md](./playbooks/timeout-issue.md) |
+| Healing Agent — No License / Heals Available | High | Robot log contains `"No available license / Agentic units to perform healing analysis and recovery"` (or, corroborating: HA enabled + 22-byte healing-data ZIP + `Allowed.AgentService == 0`) | [healing-agent-no-license.md](./playbooks/healing-agent-no-license.md) |
+| Healing Agent — No Recovery Data | Low | Healing Agent enabled but no recovery data generated after failure (license OK; connectivity / classic activity / image-only target) | [no-recovery-data.md](./playbooks/no-recovery-data.md) |

package/skills/uipath-troubleshoot/references/investigation_guide.md

@@ -0,0 +1,60 @@
+# Generic Investigation Guide
+
+Always apply these rules. If a product-specific `investigation_guide.md` exists, apply it **in addition** to these.
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Timestamp** — data falls within the time window the user described (or is recent enough to be relevant if no time was specified)
+- **Entity identity** — the entity in the data (job, queue item, process, asset, etc.) is the one the user asked about, not a different one with a similar name
+- **Environment** — data comes from the correct tenant, folder, or environment the user is working in
+- **Causal relevance** — the data is about the problem itself, not about a side effect or unrelated event that happened around the same time
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Interpreting Query Results
+
+- **Empty results or 404** — before concluding an entity doesn't exist, verify the container (folder, tenant, instance) is still accessible. If the container was deleted or returns 404, all scoped queries are unreliable. Widen the search (different folder, broader time window, different state filters) or flag as a data gap and ask the user. Never treat empty results from an inaccessible container as proof of absence.
+- **Live infrastructure data** — machine connectivity, license counts, connection health, and robot availability reflect current state, not historical state. For incidents older than 24 hours, this data shows what's true NOW, not what was true when the incident happened. Use it as context only — machines could have been online 6 months ago and gone offline since. Never use current infrastructure snapshots as causal evidence for past incidents.
+
+## Testing Prerequisites
+
+Gather and verify these before drawing conclusions on any hypothesis:
+
+1. **Reproduce the scope** — confirm you're looking at the same entity, environment, and time window the user reported
+2. **Execution path** — trace what actually happened step by step (don't infer from final status alone)
+3. **Error message** — read the full error, not just the type; details in the message often point to the root cause
+4. **Configuration state** — check relevant settings/configuration at the time of failure; don't assume defaults
+5. **Recent changes** — ask whether anything changed recently (deployments, config updates, infrastructure) that correlates with when the issue started
+6. **Dependencies** — check upstream and downstream systems; a failure in one layer often manifests as symptoms in another
+
+## Expected Outcome — Establish Before Investigating
+
+Before starting any investigation, establish what the user expects from the troubleshooting — do they want to understand the root cause, get a fix, confirm a suspicion, or something else?
+
+1. **Try to infer** the expected outcome from the user's problem description and how they framed the request
+2. **If you cannot infer**, present the user with the options you identified (e.g., "Are you looking for the root cause, a quick fix, or help understanding why this happens intermittently?") and let them choose
+3. **If you have no options**, ask the user directly what outcome they need from this investigation
+
+Do NOT begin triage or hypothesis generation until the expected outcome is clear. It determines what depth of investigation is appropriate and what a useful resolution looks like.
+
+## Tool Boundary — uip CLI Only
+
+All platform interaction MUST go through `uip` CLI commands. Do NOT work around CLI limitations by:
+
+- Calling Orchestrator REST APIs directly (e.g., via `curl` or any HTTP client)
+- Reading auth tokens from `%APPDATA%/uipath-cli/.auth` or any other credential store
+- Using undocumented or internal API endpoints
+- Constructing OData URLs manually
+
+If the `uip` CLI does not provide a command for the data you need, that data is **unavailable**. Report the gap to the user and continue the investigation with what you have. Do NOT attempt to bypass the CLI, and do NOT suggest or mention internal API endpoints, OData URLs, auth token locations, or any other workaround to the user — even as a "for your information" or "if you want to do it yourself" suggestion.
+
+## Scope Boundary — Internal Platform Issues
+
+This troubleshooting tool operates from the **client perspective**. Do NOT attempt to investigate internal platform issues (implementation bugs, server-side defects, infrastructure internals). You have no visibility into them and testing hypotheses about them wastes the user's time.
+
+- If evidence points to a **known limitation or platform bug**: present it to the user as a known issue, link to documentation if available, and suggest workarounds or contacting UiPath support
+- If evidence rules out all client-side causes and the remaining explanation is an internal platform issue: **stop testing** and tell the user the problem appears to be on the platform side, recommend they open a support ticket with the evidence gathered so far
+- Do NOT fabricate hypotheses about internal platform behavior you cannot observe or verify
+- Do NOT ask the user to investigate server logs, database state, or infrastructure they don't control

package/skills/uipath-troubleshoot/references/knowledge-base-guide.md

@@ -0,0 +1,110 @@
+# Troubleshooting Knowledge Base Guide
+
+This document describes how the troubleshooting knowledge base is structured, what each part does, and how to create new content.
+
+## Structure
+
+```
+references/
+  summary.md                            <- Entry point. Routes agents to the correct product.
+  investigation_guide.md                <- Generic investigation rules (all products).
+  templates/                            <- Templates for creating new playbooks.
+  products/{id}/                        <- One folder per product.
+    overview.md                         <- (optional) Product overview and dependencies.
+    investigation_guide.md              <- (optional) Product-specific investigation rules.
+    presentation.md                     <- (optional) Product-specific display rules.
+    summary.md                          <- (required) Playbook index with confidence levels.
+    playbooks/                          <- (required) Individual playbook files.
+  activity-packages/{id}/               <- One folder per activity package (same structure).
+```
+
+## Product / Activity Package Container
+
+Each product or activity package has its own folder containing:
+
+### overview.md (optional)
+
+A summary describing the system and what it does. What features it provides, what it depends on, what kind of issues users encounter with it.
+
+### investigation_guide.md (optional)
+
+A specific investigation guide detailing what the agent must look out for when investigating issues for that particular product.
+
+For example, in Orchestrator the agent must verify:
+- The product it is investigating is the same as the process the client referred to
+- The data gathered is from the correct folder
+- The logs, traces, and jobs are related to the actual robot that the user referenced
+
+Each product has different concerns. UI Automation needs to verify the correct activity and selector. Maestro needs to verify the correct BPMN process and task. This guide captures those product-specific verification rules.
+
+### presentation.md (optional)
+
+Product-specific display rules for how to format entity names, IDs, and labels in user-facing output. Defines how to refer to the product's entities (e.g., connections by display name, jobs by process name, instances by BPMN process name). The presenter agent discovers and reads these directly based on the domains in `state.json.scope.domain`.
+
+### summary.md (required)
+
+The playbook index. Lists all playbooks for this product, organized by confidence level. This is how agents discover which playbooks exist and their confidence. Every new playbook must be added here.
+
+### playbooks/ (required)
+
+The actual playbook files. Each file is a standalone, self-contained playbook covering one issue or one known error pattern.
+
+When an issue has multiple distinct sub-scenarios (e.g., "Orchestrator Down" can be IIS crash, startup failure, or redirect loop), create separate standalone playbooks for each sub-scenario: `orchestrator-down-forcibly-closed.md`, `orchestrator-down-startup-failure.md`, `orchestrator-down-redirect-loop.md`. Each playbook's `## Context` covers its own causes and patterns. The summary lists all of them — triage matches the right ones, and hypotheses are tested in confidence order (high first).
+
+## Playbooks
+
+Every playbook uses the same structure: `## Context`, `## Investigation`, `## Resolution`. The difference between playbooks is how much you know about the issue when writing it.
+
+| Confidence | What you know | `## Context` | `## Investigation` | `## Resolution` | Example |
+|---|---|---|---|---|---|
+| **High** | Exact error → exact cause | Match pattern + root cause | Quick verification (1-2 steps) | Concrete fix | "GetAsset" error → asset missing in folder |
+| **Medium** | Specific error → known troubleshooting path | Causes, patterns, what to look for | Concrete troubleshooting steps | Fixes mapped to findings | SSL cert invalid → check cert, chain, trust store |
+| **Low** | General symptoms → multiple possible causes | Causes, patterns, what to look for | General data gathering guidance (or absent) | Optional | Robot unresponsive → could be heartbeat, network, or machine issue |
+
+### How to decide what to write
+
+- **Do you know the exact cause from the error alone?** Write a high-confidence playbook. One verification step, one fix.
+- **Do you have a repeatable troubleshooting path?** Write a medium-confidence playbook. Step-by-step investigation that leads to the answer.
+- **Do you only know what to look for?** Write a low-confidence playbook. Describe the symptoms, causes, and what data to gather. The agent reasons from there.
+
+You can always start with low confidence and upgrade later as you learn more about the issue.
+
+### Standard Headers
+
+All playbooks use the same three headers:
+
+| Section | What goes here | Who reads it |
+|---------|---------------|-------------|
+| `## Context` | What the issue is, what causes it, what to look for. Always present. | Generator (to produce hypotheses — 1 for high-confidence, 2-5 for medium/low). Tester (for understanding). |
+| `## Investigation` | Steps to troubleshoot or verify. Can be absent for low-confidence playbooks. | Tester (follows steps if present, reasons freely if absent). |
+| `## Resolution` | Known fixes. Can be absent if the fix depends on what the investigation finds. | Presenter (assembles fixes for the user). |
+
+Template: `templates/playbook-template.md`
+
+> **Note:** The canonical confidence-level behavior table (how each agent acts per confidence level) is in `agents/shared.md`. Keep this guide aligned with that table.
+
+### Cross-Product References
+
+Playbooks may reference other product domains (e.g., an Orchestrator playbook mentioning "ProcessOrchestration" or "BPMN", a Maestro playbook referencing child Orchestrator jobs). When writing playbooks, use explicit product names when describing cross-domain behavior — the scope checker agent detects these references and flags missing domains for the orchestrator to expand scope.
+
+## How Agents Use This
+
+### Triage
+
+Reads `summary.md` to find the right product, then reads the product's `summary.md` to find ALL matching playbooks. Records every match with its confidence in `state.json`. Multiple playbooks may describe the same issue — all are recorded. Triage does NOT read playbook contents or do cross-domain expansion — the scope checker handles domain detection separately.
+
+### Hypothesis Generation
+
+The generator reads `## Context` from matched playbooks and produces hypotheses per the confidence-level behavior table in `agents/shared.md`. Hypotheses are tested in confidence order (high first).
+
+### Testing
+
+The tester reads `## Context` for understanding, then scopes work per the confidence-level behavior table in `agents/shared.md`.
+
+### Investigation Guides
+
+The investigation guide (generic + product-specific) tells agents how to verify their data is correct before drawing conclusions. Applied regardless of playbook confidence.
+
+## Creating New Content
+
+Template is in `references/templates/playbook-template.md`. Copy it, set the `confidence` field in the frontmatter (high, medium, or low), fill in the sections, and add the entry to the product's `summary.md`. The summary's Confidence column must match the playbook's frontmatter.

package/skills/uipath-troubleshoot/references/products/agents/playbooks/context-grounding-index-not-found.md

@@ -0,0 +1,94 @@
+---
+confidence: high
+---
+
+# Context Grounding Index Not Found
+
+## Context
+
+What this looks like:
+- Agent job faults during a tool call; `uip agent run status <job-id> --output json` shows `Faulted`
+- `uip traces spans get <trace-id> --output json` contains a span with `SPANTYPE: contextGroundingTool` or `toolCall` whose `ATTRIBUTES.error` contains:
+  ```
+  ContextGroundingIndex not found Code: AGENT_RUNTIME.UNEXPECTED_ERROR
+  ```
+- Full error prefix: `Unexpected Error Details: An unexpected error occurred during agent execution, please try again later or contact your Administrator. Error Details: ContextGroundingIndex not found`
+
+What can cause it:
+- The grounding index referenced in the agent's configuration was deleted from Data Service after the agent was published
+- The agent was published pointing to an index in a different folder or tenant than where it is deployed
+- The index name or ID in `agent.json` was changed manually and does not match any existing index
+- The index was never created — the agent was published with a placeholder or stale reference
+
+What to look for:
+- The `contextGroundingTool` span appears before the `agentRun` fault — the index lookup happens at tool-call time, not at startup
+- Whether the agent was recently re-deployed or the index was recently modified
+
+## Investigation
+
+1. Get the job trace ID:
+
+   ```bash
+   uip agent run status <job-id> --output json \
+     --output-filter "traceId"
+   ```
+
+2. Find the `contextGroundingTool` span and extract the index reference:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?spanType == 'contextGroundingTool'].{name: name, error: attributes.error, attrs: attributes}"
+   ```
+
+3. Note the span `name` and any index identifier visible in `attrs` — this is the index the agent tried to resolve.
+
+4. Open the local agent project and list configured context resources:
+
+   ```bash
+   uip agent context list --output json
+   ```
+
+   Note the index name the agent references.
+
+5. Check whether that index exists in the deployment folder:
+
+   ```bash
+   uip context-grounding list --folder-path "<folder-path>" --output json
+   ```
+
+   If the index name is absent from the output, the index was deleted or never created. If present, check its status field — anything other than `Active` indicates it is not ready.
+
+## Resolution
+
+**If the index was deleted — re-create it:**
+
+  ```bash
+  uip context-grounding create --index-name "<index-name>" --bucket-source "<bucket-name>" --folder-path "<folder-path>" --output json
+  uip context-grounding ingest --index-name "<index-name>" --folder-path "<folder-path>" --output json
+  ```
+
+  No agent republish needed — the runtime resolves by name.
+
+**If the index exists but is in a different folder — re-link the agent:**
+
+  ```bash
+  uip agent context remove --name "<old-index-name>" --output json
+  uip agent context add --name "<correct-index-name>" --folder-key "<folder-key>" --output json
+  uip agent publish --output json
+  ```
+
+**If the index reference in `agent.json` is stale or wrong:**
+- Correct the index name in `agent.json` → `context` block to match an existing index from `uip context-grounding list`
+- Republish: `uip agent publish --output json`
+
+**If the index was never created:**
+
+  ```bash
+  uip context-grounding create --index-name "<index-name>" --bucket-source "<bucket-name>" --folder-path "<folder-path>" --output json
+  uip context-grounding ingest --index-name "<index-name>" --folder-path "<folder-path>" --output json
+  uip agent context add --name "<index-name>" --folder-key "<folder-key>" --output json
+  uip agent publish --output json
+  ```
+
+**If none of the above — the index exists but the runtime cannot resolve it:**
+- Capture `uip traces spans get <trace-id> --output json` and escalate to the Agents team with the full span output and the index name

package/skills/uipath-troubleshoot/references/products/agents/playbooks/input-schema-validation-failure.md

@@ -0,0 +1,89 @@
+---
+confidence: high
+---
+
+# Input Schema Validation Failure
+
+## Context
+
+What this looks like:
+- Agent job faults at startup; `uip agent run status <job-id> --output json` shows `Faulted`
+- `uip traces spans get <trace-id> --output json` contains an `agentRun` span whose `ATTRIBUTES.error` matches one of two variants:
+
+  **Variant A — agent configuration schema:**
+  ```
+  Agent configuration invalid Details: ... agent.json failed schema validation: 1 validation error for AgentDefinition <field-path>
+  ```
+
+  **Variant B — input payload schema:**
+  ```
+  Input validation failed Details: Data failed json schema validation: 1 validation error for DynamicType_0 BatchJson <field-name>
+    <type-error> [type=<type_code>, input_value=...]
+  ```
+
+What can cause it:
+- **Variant A:** `agent.json` contains a field with the wrong type — e.g., a string value where an object is expected (`folderPathPrefix`, `escalation.channels`). Usually introduced after a manual edit or a failed schema migration.
+- **Variant B:** The input payload passed to `uip agent run start` (or the caller API) omits a required field or passes a wrong type — e.g., a dict where a string is expected, or a missing required key.
+
+What to look for:
+- The error names the exact field path (`resources.0.context.settings.folderPathPrefix`) and the type mismatch — use this to locate the offending value immediately
+- Variant A faults before any LLM call (the agent never starts); Variant B faults at invocation time
+
+## Investigation
+
+1. Get the job trace ID:
+
+   ```bash
+   uip agent run status <job-id> --output json \
+     --output-filter "traceId"
+   ```
+
+2. Pull the failing `agentRun` span error:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?spanType == 'agentRun'].attributes.error"
+   ```
+
+3. Determine the variant from the error prefix:
+   - `Agent configuration invalid` → **Variant A** — `agent.json` is misconfigured
+   - `Input validation failed` → **Variant B** — caller passed a bad payload
+
+4. **Variant A only** — validate the agent project locally:
+
+   ```bash
+   uip agent validate --output json
+   ```
+
+   The validator names the same field path as the span error. Confirm the offending field and its current value in `agent.json`.
+
+5. **Variant B only** — the error names the exact offending field and type mismatch inline (e.g., `Field required [type=missing, ...]` or `Input should be a valid string [type=string_type, ...]`). Use the field name from the error directly — no need to diff the full schema.
+
+## Resolution
+
+**Variant A — fix `agent.json`:**
+- Open `agent.json` and locate the field named in the error (e.g., `resources[0].context.settings.folderPathPrefix`)
+- Correct the value to match the expected type (the error states `Input should be an object` / `Input should be a valid string` etc.)
+- Re-validate before republishing:
+
+  ```bash
+  uip agent validate --output json
+  uip agent publish --output json
+  ```
+
+**Variant B — fix the input payload:**
+- If a required field is missing: add it to the invocation call or the `uip agent run start` arguments
+- If a field has the wrong type: correct the type to match the schema (e.g., pass a plain string instead of a dict)
+- If the schema itself needs updating to match new caller expectations — add or modify the input parameter:
+
+  ```bash
+  uip agent input add --name "<param-name>" --type string --output json
+  uip agent publish --output json
+  ```
+
+- Re-invoke with the corrected payload:
+
+  ```bash
+  uip agent run start --agent-name "<name>" --folder-id <id> \
+    --input '{"<param-name>": "<value>"}' --output json
+  ```