@uipath/skills 1.197.0 → 1.197.2

package/skills/uipath-troubleshoot/SKILL.md

@@ -1,175 +1,106 @@
 ---
 name: uipath-troubleshoot
-description: "UiPath troubleshooting, diagnostics, and root-cause investigations across any UiPath product, feature, runtime, or artifact. Investigates errors, failures, faults, exceptions, regressions, performance problems, unexpected behavior, and silent malfunctions — answers why something failed, broke, stopped, hung, slowed down, returned wrong results, lost access, or stopped working after a change. Walks the available evidence (logs, traces, incidents, status fields, configuration, history) to identify the originating fault and explain what changed."
-when_to_use: "User asks why something failed, broke, stopped, hung, was stuck, returns wrong results, or behaves unexpectedly in any UiPath system. Triggers: 'why did X fail', 'find the cause', 'find why', 'what changed', 'investigate', 'diagnose', 'debug this', 'triage', 'help me figure out', 'what's wrong', 'root cause', 'fix this error', 'inspect this trace / incident / log / job / instance', 'X worked yesterday but now …'. Also fires on raw error messages, exception stacks, error codes, job / queue IDs, or 'stuck / orphan / zombie' state descriptions."
+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; 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. For operating resources without causal investigation→uipath-platform; for applying a known source fix→the artifact owner."
+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. 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
 
-Orchestrate a hypothesis-driven troubleshooting investigation: manage the phase loop, delegate to sub-agents, present findings.
+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).
 
-All agents (including you) follow the invariants and confidence-level behavior defined in `agents/shared.md` (§ Invariants, § Confidence-Level Behavior).
+## 1. Invariants
 
-## 1. Critical Rules
+ALL phases. Never override.
 
-1. **You NEVER run uip commands, query endpoints, or read reference docs.** Sub-agents do everything else.
-2. **You NEVER confirm/eliminate hypotheses yourself.** Always spawn a tester.
-3. **You own all decisions:** phase transitions, root cause vs. symptom classification, when to present resolution.
-4. **You present the presenter's output verbatim.** The presenter agent formats all findings — you do not rewrite or reformat them. The one exception: you parse and act on the `## Post-presentation actions` block (see §6).
-5. **Test hypotheses one at a time, sequentially.** Never spawn parallel testers.
-6. **When you need user input, use `AskUserQuestion`.** Do not proceed until the user responds.
+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. **No CLI discovery.** Run only uip commands documented in a product overview's CLI section, a matched playbook's `## Investigation` section, or an investigation guide. No guessed names or flags, no `--help` exploration, no raw REST/curl workarounds. Empty results from documented commands are evidence; results from undocumented commands are contract violations.
+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.
+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.** Diagnosis is autonomous; applying a fix is not. **Modifying user source files, or executing a remediation command that changes tenant/platform state (a `## Resolution` step that creates, deletes, or reconfigures a resource), requires explicit approval via `AskUserQuestion`.** 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 or non-answer: do not edit or execute. If AskUserQuestion is unavailable, present the proposed fix as text and stop.
+11. **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.
 
-## 2. Investigation State
+**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).
 
-All state lives in `.local/investigations/` (relative to working directory). Schemas in `schemas/`.
+**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.
 
-| File | Purpose | Writers |
-|------|---------|---------|
-| `state.json` | Scope, phase, matched playbooks | triage, orchestrator |
-| `hypotheses.json` | All hypotheses + status | generator, tester, orchestrator |
-| `evidence/*.json` | Interpreted summaries | triage, tester |
-| `raw/*.json` | Full raw CLI/API responses | triage, tester |
-| `scope-check.json` | Domain expansion verdict | scope-checker |
-| `depth-check.json` | Depth-gate verdict on confirmed root causes | depth-verifier |
-| `needs_input.json` | User-input request (sub-agent halts; orchestrator reads it, asks via `AskUserQuestion`) | triage, generator, tester |
+**Progress:** track phases with TaskCreate/TaskUpdate, subjects tailored to the user's problem.
 
-Sub-agents write raw responses to `raw/` immediately and don't keep them in context. You read evidence summaries, not raw files.
+## 2. Anchor & primary evidence
 
-## 3. Phase State Machine
+1. **Classify (system, entity) from the user's message.** Cross-check against `references/summary.md` domains.
+2. **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.
+3. **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.
+4. **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.
 
-Update `state.json.phase` at each transition:
+## 3. Extract signals
 
-| Phase | Entry condition | Next |
-|-------|----------------|------|
-| `triage` | User describes problem (or new data arrives) | `hypotheses` |
-| `hypotheses` | Triage complete, playbooks matched | `test` |
-| `test` | Hypotheses ready, testing next in confidence order | `evaluate` |
-| `evaluate` | Tester returns verdict | `deepen`, `test`, or `depth_check` |
-| `deepen` | Confirmed symptom needs sub-hypotheses | `hypotheses` (re-invoke generator) |
-| `depth_check` | Hypothesis confirmed as root cause | `resolution` (verified), `test` (one re-round), or halt (write `needs_input.json`) |
-| `resolution` | Depth check verified, or all hypotheses exhausted | `complete` |
-| `complete` | Findings presented to user | — |
+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.
 
-## 4. Investigation Flow
+**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.
 
-### TRIAGE
+**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.
 
-1. **Spawn triage** (`agents/triage.md`). Pass the user's problem **as-is** — do NOT pre-classify or constrain scope.
-2. **Sanity gate.** Verify triage evidence relates to the reported problem (process/entity/time window). If it's about a different entity: discard, inform the user, re-spawn or ask for clarification.
-3. **Scope check.** Spawn scope-checker (`agents/scope-checker.md`); read its `scope-check.json`. Missing domains (`missing_domains`) → `AskUserQuestion` whether to expand; if approved, re-spawn triage with them. Unnecessary domains (`unnecessary_domains`) → remove from `state.json.scope.domain`.
-4. **User input.** If triage returned `needs_user_input: true`, ask via `AskUserQuestion`, then **continue the existing triage agent** via `SendMessage` — do NOT spawn a fresh one (a fresh spawn re-discovers everything from scratch). Re-spawn only if the answer fundamentally changes scope (different product/entity type).
+## 4. Route
 
-**Never skip the hypothesis loop.** Even conclusive-looking triage evidence proceeds through GENERATE → TEST → EVALUATE. Triage classifies and gathers data — it does not determine root cause; a non-obvious cause surfaces only in the test cycle.
+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.
 
-### GENERATE HYPOTHESES
+- **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`.
 
-Spawn hypothesis generator (`agents/hypothesis-generator.md`). Behavior varies by confidence level per the table in shared.md.
+## 5. Walk the playbook
 
-### TEST HYPOTHESES
+1. 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).
+2. 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.
+3. 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.
+4. **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.
+5. **For large result sets**, summarize at write-time — group by type, count patterns, extract samples. Never slice raw responses with arbitrary limits.
 
-Test every hypothesis sequentially (highest confidence first). For each, spawn hypothesis tester (`agents/hypothesis-tester.md`).
+## 6. Verification checklist — mandatory before presenting
 
-### EVALUATE (after each test)
+Write the answers in notes.md; do not skip items, do not present without them:
 
-**Validate:** Reject and re-spawn if `elimination_checks` are missing/incomplete. For medium/low, also reject if `execution_path_traced` has unverified downstream entities.
+1. **Cause named:** quote ONE item verbatim from the playbook's "What can cause it" list — not a category, not a vague generalization.
+2. **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.
+3. **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. 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.
+4. **Resolution aligned:** the fix is the playbook's `## Resolution` branch keyed to that exact cause.
+5. **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.
+6. **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; alternatives go as labeled options.
 
-**Reactive scope check:** If evidence references entities/errors from an out-of-scope domain, spawn scope-checker and act on its `scope-check.json` (`missing_domains` / `unnecessary_domains`). Otherwise skip.
+Any check fails → ONE targeted re-fetch for the missing datum. Still failing →
 
-**Classify and act:**
+- **Diagnostic-recommendation terminal** (legitimate outcome, not failure): when evidence cannot separate sibling causes and 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.
 
-Before classifying as **explains-WHY**, apply the upstream-cause gate. The mechanism (explicit-event check + implicit-presupposition check) is owned by the depth-verifier — see [`agents/depth-verifier.md` § Causal precedence](agents/depth-verifier.md). Orchestrator decision rule: if the gate identifies any upstream condition that has a `pending` or `supported` sibling hypothesis answering it, classify the current hypothesis as **describes-WHAT** regardless of evidence strength.
+## 7. Escalation triggers
 
-**Sibling-precedence backstop** (orchestrator-only — siblings are visible here, not to the depth-verifier): if the candidate root cause is a persistence, propagation, cleanup, or state-transition pattern AND any sibling hypothesis is `pending` AND that sibling questions whether the underlying state has its own originating fault, the sibling MUST be tested before the candidate can be classified as **explains-WHY**. Stopping at the first confirmed hypothesis is incorrect when that hypothesis is downstream.
+Load `references/escalation.md` when ANY of:
 
-- **Eliminated / Inconclusive** → record, test next hypothesis
-- **Confirmed — explains WHY** (and passes upstream-cause gate) → root cause. Go to DEPTH CHECK (do **not** jump straight to Resolution). Multiple confirmed root causes: depth-check each before skipping the rest.
-- **Confirmed — describes WHAT only** → symptom. Re-invoke generator with `trigger: "deepening"` and `parent_hypothesis`.
-- **All playbook hypotheses eliminated** → re-invoke generator with `trigger: "scope_adjustment"` and eliminated IDs to produce from docsai (every matched playbook — all confidence levels — was already drafted in the single round).
+1. **No playbook grep match** — silent failure, hang, wrong results, nothing greppable.
+2. **≥2 co-equal matches** with distinct, independent signatures (different activities/error codes, neither upstream of the other).
+3. **Cross-domain chain deeper than one hop**, or the one-hop follow contradicts the original match.
+4. **Decision tree exhausted** — every branch rejected, or a discriminator stays inconclusive after its named evidence is gathered.
+5. **Checklist fails after the re-fetch** and no diagnostic-recommendation terminal applies.
+6. **Evidence or new user data contradicts the matched playbook's core precondition.**
 
-**Co-equal-roots guard.** Before applying any "skip remaining" exit after a confirmed+verified root cause, check `state.json.matched_playbooks`. If two or more playbooks are present at the same highest confidence level AND they correspond to **distinct, independent** error signatures (different activities, different error codes, neither upstream of the other), every pending hypothesis sourced from those playbooks MUST be tested before stopping. Do not exit on the first confirmed root cause when triage found multiple co-equal roots — you will under-report and miss fixes the user has to make. Only after each co-equal hypothesis is tested (confirmed, eliminated, or inconclusive) and depth-checked when confirmed do you proceed to Resolution.
+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).
 
-### DEPTH CHECK (after a hypothesis is confirmed as root cause)
+## 8. Present
 
-Spawn the depth-verifier sub-agent (`agents/depth-verifier.md`). Pass it the
-confirmed hypothesis ID(s), `state.json` path, and the matched playbook path.
-The verifier reads `hypotheses.json`, the playbook's `## Context` cause
-list ("What can cause it") and `## Resolution` section, and the evidence
-files, then writes
-`.local/investigations/depth-check.json` with one of:
+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.
 
-- `verdict: "verified"` — the confirmed hypothesis names a specific cause
-  from the playbook, has cause-specific evidence (not just symptom-level),
-  and recommends the matching resolution branch. Proceed to **Resolution**.
-- `verdict: "shallow"` — one or more depth dimensions are missing.
-  Inspect `gaps`. Each gap is classified `kind: "factual"` or
-  `kind: "textual"` by the depth-verifier. Routing rule:
-  - **If ANY gap has `kind: "factual"`** — spawn ONE additional
-    hypothesis-tester round on the same hypothesis to gather the
-    missing evidence, then re-spawn the depth-verifier. Stop after one
-    re-round. After that, either declare medium-confidence and proceed
-    to Resolution with the gaps surfaced to the user, or — if the gap
-    is a genuine data limitation — write `needs_input.json` and stop.
-  - **If ALL gaps are `kind: "textual"`** — do NOT spawn the tester.
-    Re-running the tester cannot fix narrative-level issues (paraphrase
-    looseness, wrong resolution branch picked) since those are the
-    *generator's* output, not the tester's. Accept the confirmed
-    hypothesis at `confidence: medium` and proceed to Resolution.
-    Surface the textual gaps in the presenter's output so the user
-    sees them.
+## 9. New data from the user
 
-**Symptom ≠ cause** (shared.md invariant #9): a symptom-level match confirms the playbook *match*, not the *cause*. The depth-verifier enforces this gate — do not skip it.
+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.
 
-### NEW DATA FROM USER
+## 10. Completion
 
-If the user provides new data at any point (error messages, job IDs, logs, screenshots), go back to TRIAGE. Re-spawn triage with the new data. Do NOT patch new data into an in-progress investigation.
-
-## 5. Evaluation Rules
-
-**Root cause vs. symptom:** A finding that explains WHY the failure occurs is a root cause. A finding that describes WHAT happened (but not why) is a symptom — deepen it.
-
-**When to stop testing:**
-- High-confidence root cause confirmed → DEPTH CHECK; if verified AND no other co-equal-confidence playbook is still pending (see Co-equal-roots guard above), skip remaining hypotheses and go to Resolution. If co-equal playbooks remain pending, continue testing them first.
-- Medium/low root cause confirmed → DEPTH CHECK; if verified, ask user if they want to continue
-- All hypotheses exhausted (eliminated or inconclusive) → go to Resolution with "no root cause" outcome (no depth check needed when there is nothing to gate)
-
-## 6. Resolution
-
-Spawn the presenter agent (`agents/presenter.md`) with the confirmed hypothesis IDs and **all domains from `state.json.scope.domain`**. Do NOT pre-filter domains based on your judgment of their relevance to the causal chain — the presenter classifies root cause vs. propagation domains and searches docsai for each. Excluding a domain prevents the presenter from finding error handling patterns it was designed to surface.
-
-The presenter:
-- Assembles fixes from playbook `## Resolution` sections across all domains in the causal chain
-- Searches docsai for error handling and propagation patterns for every propagation domain
-- Applies all presentation rules (entity names from raw data, display names, UI labels)
-- Gates every fix step against documented sources
-
-Present the presenter's output verbatim to the user. After presenting:
-
-**Execute Post-presentation actions FIRST.** If the presenter's output has a `## Post-presentation actions` section, run every action in order before any generic follow-up. For each action:
-
-1. Print the "Print as plain text" block exactly as written, separate from the question (raw XML/selectors render poorly inside `AskUserQuestion` options/previews).
-2. Print the warning string verbatim if non-empty.
-3. Call `AskUserQuestion` with the action's question and options. Ask the project path (or other missing input the action declares) in the same call.
-4. If the user accepts, execute the "On user accept" procedure exactly as written — do not improvise. If it references a sub-skill (e.g., `uia-improve-selector`), follow its USAGE.md; otherwise apply the documented direct-edit path and run any validation command listed.
-5. If the user declines, stop the action; do not modify files. Move to the next.
-6. If the action's `Status` is `blocked` (missing evidence), surface it as a follow-up instead of asking the user to approve an incomplete fix — name the missing evidence field and the agent that should have populated it.
-
-Do NOT skip the Post-presentation actions block when:
-- The matched playbook was downgraded from `high` to `medium` by depth-check (the resolution procedure is preserved across confidence downgrades — see `agents/depth-verifier.md` on textual gaps).
-- The depth-verifier flagged a cause-name mismatch (textual gap). A reclassified cause does NOT invalidate the playbook's interactive resolution; both can be reported together.
-- The recovered/recommended data was produced in a recommendation-only or unproven mode (`InferredRecoveryInfo`, `RecoverySuccessful: false`). The action carries a warning string for exactly this case — present it and let the user decide.
-
-Only after all actions are complete (accepted, declined, or surfaced as blocked) proceed to the generic follow-up:
-
-**If root cause found** — offer to help implement any further changes or clean up `.local/investigations/`.
-
-**If no root cause found** — use `AskUserQuestion` to offer: provide more data (re-triage), or open a UiPath support ticket with the evidence gathered.
-
-## 7. Operational Details
-
-**Spawning:** Read agent files just-in-time — only `agents/shared.md` + the specific agent file when you're about to spawn. Include full instructions and context in the prompt.
-
-**Reasoning effort:** Where the spawn tool exposes a reasoning-effort parameter, set it per role. `low` for the mechanical step-followers — triage, hypothesis-tester, presenter — they execute documented playbook/investigation steps and do not need deep reasoning. `high` for the judgment roles — hypothesis-generator, scope-checker, depth-verifier.
-
-**Progress:** Use `TaskCreate`/`TaskUpdate` for each phase. Tailor subjects to the user's problem.
-
-**Cleanup:** After investigation completes, offer to delete or preserve `.local/investigations/`.
+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.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-action-failed-after-find.md

@@ -86,7 +86,7 @@ Walk the branches; pick the first whose evidence holds. Name the evidence that r
 
 ## Post-presentation actions
 
-This resolution is **interactive** whenever a fix edits user source files — Branch A (credential wiring), Branch B (add wait / change `DelayBefore` / drop a stale `InRegion`), Branch C (`MethodType` change), and Branch D (`Text` edit) all touch the workflow. The orchestrator MUST call `AskUserQuestion` before any edit.
+This resolution is **interactive** whenever a fix edits user source files — Branch A (credential wiring), Branch B (add wait / change `DelayBefore` / drop a stale `InRegion`), Branch C (`MethodType` change), and Branch D (`Text` edit) all touch the workflow. You MUST call `AskUserQuestion` before any edit (approval gate).
 
 1. **Sharing a file path is not approval.** A path given so you could read the project does not authorize editing it. Issue a separate `AskUserQuestion` before any write.
 2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the concrete diff and confirm separately.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-cell-targeting-failures.md

@@ -99,7 +99,7 @@ Fix: row indices over scrolled tables are unreliable — the model re-indexes fr
 
 Branches A–E all end in a **workflow source edit** (descriptor `CellExtraInfo` change, `Version` bump, scroll/targeting change). This resolution path is **interactive**.
 
-1. The orchestrator MUST call `AskUserQuestion` before any edit: print the exact file path, the activity `IdRef`, the property (e.g. `Version`, `Descriptor.Target.CellExtraInfo.ColumnIndex`), and the current → proposed value.
+1. You MUST call `AskUserQuestion` before any edit (approval gate): print the exact file path, the activity `IdRef`, the property (e.g. `Version`, `Descriptor.Target.CellExtraInfo.ColumnIndex`), and the current → proposed value.
 2. **Sharing a file path is not approval.** A path the user gave for reading does not authorize editing — issue a separate `AskUserQuestion` before writing.
 3. Never bundle "gather input" with "apply fix" in one option — split into gather, then surface the concrete diff and confirm.
 4. The apply-fix question must show the concrete diff (file, `IdRef`/line, current value, proposed value). Vague approvals are not enough.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-element-not-found.md

@@ -108,7 +108,7 @@ Walk the decision tree. Choose the first branch whose evidence holds. Do not app
 
 ## Post-presentation actions
 
-This resolution is **interactive** — every applicable fix edits user source files (the activity `Descriptor`, `TimeoutMS`, `CVScope` `Target`/`OCREngine`/`CvMethod` properties, or adds a readiness/check activity). Before any edit, the orchestrator MUST call `AskUserQuestion`. Rules:
+This resolution is **interactive** — every applicable fix edits user source files (the activity `Descriptor`, `TimeoutMS`, `CVScope` `Target`/`OCREngine`/`CvMethod` properties, or adds a readiness/check activity). Before any edit, you MUST call `AskUserQuestion` (approval gate). Rules:
 
 1. **Sharing a file path is not approval.** A path the user gave for reading the workflow does not authorize editing it. Issue a separate `AskUserQuestion` before any write.
 2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the concrete diff and confirm separately.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-get-text-empty-or-wrong-result.md

@@ -16,6 +16,7 @@ What this looks like:
 - `Result` holds text from a **previous** screen state (stale), not the screen as it is now.
 - `Result` is partial — a few words missing, or words half-clipped at the edge of the read region.
 - No error message in the logs for any of the above (silent). The two exception branches below are the exceptions.
+- Design-time warning "The Select methods only work on editable text" — clipboard mode configured on a non-editable target.
 
 What can cause it (ordered most → least common):
 - **OCR scrape failed silently.** `MethodType = OCR`. The OCR engine threw; the failure is caught, traced, and swallowed, producing **zero** OCR words for the region. The activity then composes text from an empty word set → `Result = ""`. No fault is raised.
@@ -102,7 +103,7 @@ Fix:
 
 ## Post-presentation actions
 
-Branches B, C, E (the switch-to-OCR fix), and G edit user workflow files (the `RefreshBefore` / `MethodType` / `Scroll`-related properties of the CV Get Text activity, or `ScrollOffset` / `DelayScreenshotAfterScroll` / `OCREngine` on the CV Screen Scope). This resolution path is **interactive**. Before any edit, the orchestrator MUST call `AskUserQuestion`.
+Branches B, C, E (the switch-to-OCR fix), and G edit user workflow files (the `RefreshBefore` / `MethodType` / `Scroll`-related properties of the CV Get Text activity, or `ScrollOffset` / `DelayScreenshotAfterScroll` / `OCREngine` on the CV Screen Scope). This resolution path is **interactive**. Before any edit, you MUST call `AskUserQuestion` (approval gate).
 
 Rules the agent MUST follow:
 

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-invalid-descriptor.md

@@ -89,7 +89,7 @@ Fix: correct the expression named in `Descriptor value: '<expression>'`.
 
 ## Post-presentation actions
 
-Every fix above edits user source files (the `Descriptor` argument binding, the descriptor-building code, or re-capture in XAML). The resolution is **interactive** — the orchestrator MUST obtain explicit approval before any edit.
+Every fix above edits user source files (the `Descriptor` argument binding, the descriptor-building code, or re-capture in XAML). The resolution is **interactive** — you MUST obtain explicit approval via `AskUserQuestion` before any edit.
 
 1. **Sharing a file path is not approval.** A path the user gave for reading the project does not authorize editing it. Issue a separate `AskUserQuestion` before any edit.
 2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the concrete diff and confirm separately.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-scroll-search-failures.md

@@ -99,7 +99,7 @@ Evidence: `CvElementExistsWithDescriptor` with `ScrollDirection != None` returns
 
 ## Post-presentation actions
 
-Branches A, B, C, and E may end in edits to the user's workflow files (changing `ScrollDirection` / `NumberOfScrolls` / `DelayScreenshotAfterScroll` on the activity, `ScrollOffset` on the CV Screen Scope, or restructuring the scope). When a recommended fix edits a source file, the resolution is **interactive**. The orchestrator MUST call `AskUserQuestion` before any edit.
+Branches A, B, C, and E may end in edits to the user's workflow files (changing `ScrollDirection` / `NumberOfScrolls` / `DelayScreenshotAfterScroll` on the activity, `ScrollOffset` on the CV Screen Scope, or restructuring the scope). When a recommended fix edits a source file, the resolution is **interactive**. You MUST call `AskUserQuestion` before any edit (approval gate).
 
 1. **Sharing a file path is not approval.** A path the user gave for reading the project does not authorize editing it. Issue a separate `AskUserQuestion` before any edit.
 2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather input, then surface the concrete diff and confirm separately.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-silent-failures-and-false-results.md

@@ -111,7 +111,7 @@ Fix: set `CvMethod` to include the families the descriptors need (control detect
 
 ## Post-presentation actions
 
-This resolution path is **interactive** whenever the fix edits the user's workflow — changing `ContinueOnError`, clearing or rebinding `InRegion`, changing `MethodType` / `RefreshBefore`, correcting a cell descriptor, or changing the scope's `CvMethod`. The orchestrator MUST call `AskUserQuestion` before any edit, and follow these rules:
+This resolution path is **interactive** whenever the fix edits the user's workflow — changing `ContinueOnError`, clearing or rebinding `InRegion`, changing `MethodType` / `RefreshBefore`, correcting a cell descriptor, or changing the scope's `CvMethod`. You MUST call `AskUserQuestion` before any edit (approval gate), and follow these rules:
 
 1. **Sharing a file path is not approval.** A path the user gave for reading the project does not authorize editing it. Issue a separate `AskUserQuestion` before any edit.
 2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the specific diff and confirm separately.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/delete-range-failures.md

@@ -54,12 +54,13 @@ Go in this order — cheaper checks first.
    - If the expression depends on values computed earlier in the workflow (`row counts`, `lastRow`), confirm those values are valid at the moment Delete Range runs. A `lastRow` of 0 with a range expression like `"A1:B" + lastRow.ToString` produces `"A1:B0"`, which Excel COM rejects.
 
 5. **Confirm branch 3 (ShiftCells / ShiftOption conflict).** Inspect the activity configuration:
+   - **Prerequisite — branch 3 REQUIRES a `COMException` (`Application-defined or object-defined error` / `0x800A03EC`) raised by Delete Range itself.** If the Delete Range log line reads "completed successfully" (no exception) and the visible fault is a *downstream* activity (e.g. a post-condition `Throw` or a later Read Range), this is NOT branch 3 — the `ShiftCells` / `ShiftOption` values (`ShiftCellsUp`, etc.) are a red herring, not the cause. Go to branch 5 (step 6).
    - If `ShiftCells` is False, this branch does not apply — go back to step 2.
    - If `ShiftCells` is True, `ShiftOption` must be set to a valid direction. Classic `Delete Range` accepts `ShiftLeft` / `ShiftUp` / `EntireRow` / `EntireColumn`; Modern `DeleteRangeX` accepts `ShiftCellsLeft` / `ShiftCellsUp` / `EntireRow` / `EntireColumn` (naming differs slightly across versions — check the property dropdown for the host's package version).
    - Open the workbook in Excel and inspect the deletion target's surroundings: are there merged cells along the bottom edge (relevant for `ShiftUp`), the right edge (relevant for `ShiftLeft`), or anywhere Excel would need to break to perform the shift? Are there Excel Tables (`Ctrl+T`) overlapping the range? Excel Tables refuse partial-row deletions that would break the table's rectangular shape.
    - Reproduce manually: open the workbook in Excel, select the same range, `Home → Delete → Delete Cells…`, pick the same shift direction. If Excel rejects it interactively, the activity sees the same rejection wrapped in a COMException.
 
-6. **Confirm branch 5 (filter misalignment).** Open the workbook in Excel before running the workflow, OR snapshot it from a recent backup:
+6. **Confirm branch 5 (filter misalignment).** The signature is a Delete Range that "completed successfully" (no exception, N cells deleted) followed by a *downstream* failure (a post-condition `Throw`, or a later activity that can't find an expected row). In the job logs, the decisive pair is an active-AutoFilter trace line (e.g. "workbook has active AutoFilter on sheet '<name>' column '<col>'") plus the "Delete Range ... completed successfully" line — the filter silently pulled hidden rows into the coordinate range. Confirm against the workbook state:
    - Check each worksheet header row for the filter funnel icon (`Data → Filter` toggle). If active, the filter is applied — hidden rows exist.
    - `Home → Find & Select → Go To Special → Visible cells only` highlights what's visible. Compare to the configured Delete Range target: any hidden rows inside the range fall victim to the deletion silently.
    - For a workflow that builds the `Range` expression dynamically from a row count (`UsedRange.Rows.Count`), confirm whether the count includes hidden rows. The COM `UsedRange.Rows.Count` includes hidden rows; the modern OpenXML enumeration does not — provider-dependent skew.

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/investigation_guide.md

@@ -15,7 +15,7 @@ If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy.
 ## Domain-Specific Data Gathering
 
 1. **Activity execution traces** — these activities emit per-call traces. Pull them when available — they expose the exact Google REST endpoint hit, request/response status, and timing. Trace evidence narrows whether the failure originated at connection resolution, OAuth token validation, the Google API call, or post-processing inside the activity.
-2. **Route by status class and exception type, not by the message sentence.** Modern `*Connections` activities wrap most failures into a `GSuiteException` whose *text* is a friendly mapping of the underlying HTTP status — different root causes share similar wording, and one generic message (`An error occurred in the activity.`) hides the real status entirely. Before matching a playbook, read the embedded HTTP status / inner exception from the trace and classify: **401** (token rejected) and **403** (authorization/quota) and auth-phase `TimeoutException` → connection/auth or storage-quota; **404** / unresolved item → resource-not-found; **400** server-side range/cell → the Sheets playbooks; **5xx / 429 / network `HttpRequestException` / per-request `A task was canceled.`** → transient-and-timeout. Note two specific traps: a per-request timeout surfaces as `TaskCanceledException` (`A task was canceled.`), **never** as `System.TimeoutException` (which only comes from authentication); and a client-side `ArgumentException`/`NullReferenceException` (invalid/null input) is thrown before any API call, so it has no HTTP status at all.
+2. **Route by status class and exception type, not by the message sentence.** Modern `*Connections` activities wrap most failures into a `GSuiteException` whose *text* is a friendly mapping of the underlying HTTP status — different root causes share similar wording, and one generic message (`An error occurred in the activity.`) hides the real status entirely. Before matching a playbook, read the embedded HTTP status / inner exception from the trace and classify: **401** (token rejected) and **403** (authorization/quota) and auth-phase `TimeoutException` → connection/auth or storage-quota; **404** / unresolved item → resource-not-found; **400** server-side range/cell → the Sheets playbooks; **5xx / 429 / network `HttpRequestException` / per-request `A task was canceled.`** → transient-and-timeout. Note two specific traps: a per-request timeout surfaces as `TaskCanceledException` (`A task was canceled.`), **never** as `System.TimeoutException` (which only comes from authentication); and a client-side `ArgumentException`/`NullReferenceException` (invalid/null input) is thrown before any API call, so it has no HTTP status at all. One more: a raw `ConnectionHttpException` means the failure is at the **Integration Service connection layer** (connection resolution / token fetch), not at the Google API — if its message embeds a `CNS…` code, route by the exact code via the [CNS error-code reference](../../products/integration-service/cns-error-codes-reference.md) (`CNS1008` connection needs re-authentication, `CNS1006`/`CNS1049` deleted / personal-workspace, `CNS1044`/`CNS1045` scope/folder permission, `CNS2xxx` service-side); the code is more precise than the status class.
 
 ## Testing Prerequisites
 

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/connection-and-auth-failures.md

@@ -21,6 +21,8 @@ What this looks like — any of the following messages:
 
 **Design-time variant:** when picking a Drive/Sheets item in the Studio browse dialog fails with *"Items cannot be retrieved"*, the underlying cause is frequently a `ConnectionHttpException` with **HTTP 403** and code `CNS1044` (insufficient permissions) or `CNS1045` (insufficient folder permissions). This is the same authorization problem surfacing at design time instead of run time.
 
+**Any `CNS…` code in the `ConnectionHttpException` detail** identifies the exact Connection Service failure and outranks the status class — route it via the [CNS error-code reference](../../../products/integration-service/cns-error-codes-reference.md). The ones seen from these activities: `CNS1008` (connection not in authorized state → re-authenticate), `CNS1006`/`CNS1049` (connection deleted / personal-workspace), `CNS1045` (folder permission — the message names which one), `CNS2xxx` (Connection Service dependency failure — retry, then escalate).
+
 What activities can produce these errors:
 Every `*Connections` activity (all Gmail, Drive, Sheets, Docs, Calendar, Tasks, Forms, Apps Script modern activities) and every legacy `GSuiteApplicationScope` child, because all of them resolve a connection and acquire a token before doing any work. Auth-timeout is most visible on the scope/connection itself and on the first activity to execute after a cold token.
 
@@ -49,7 +51,7 @@ What can cause it:
 - **If the token is expired or revoked (401 / `authError`):** Reconnect/re-authorize the Integration Service connection (or refresh the legacy scope's credential). Confirm the Google account password/2FA didn't change and that authorization wasn't revoked in the Google account security settings.
 - **If authorization is insufficient (403 / `insufficientFilePermissions`):** Grant the authenticated account access to the target resource, or recreate the connection with the OAuth scopes the operation requires (e.g., full Drive scope rather than read-only). For the design-time `CNS1044`/`CNS1045` browse failure, the same scope/permission grant fixes the picker.
 - **If a domain policy blocks the app (`domainPolicy`):** Escalate to the Google Workspace administrator to allow the connector/app.
-- **If the connection itself failed (raw `ConnectionHttpException`):** Confirm the connection exists and is enabled in Integration Service; recreate it if it was deleted. Verify the robot has network reachability to the connection service.
+- **If the connection itself failed (raw `ConnectionHttpException`):** Confirm the connection exists and is enabled in Integration Service; recreate it if it was deleted. Verify the robot has network reachability to the connection service. If the detail carries a `CNS…` code, apply the exact remediation from the [CNS error-code reference](../../../products/integration-service/cns-error-codes-reference.md) instead of guessing from the status class.
 - **If authentication timed out:** Confirm network reachability and latency to Google's OAuth endpoint. Raise the legacy scope's `TimeoutMS` if the auth path is legitimately slow; for interactive OAuth, ensure the consent flow can complete in the robot's session (unattended robots cannot answer an interactive prompt).
 
 If the connection reconnects cleanly, the account demonstrably has access, and the error persists, the cause is outside the connection layer — re-triage against the resource-not-found or transient-error playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/investigation_guide.md

@@ -31,6 +31,7 @@ Route by message:
 - `The server is unable to process the current request.` / `Request time out.` / 500 / 504 / batched 5xx → [transient-service-error](./playbooks/transient-service-error.md).
 - Faults **before any Graph call** (`Could not retrieve the selected asset`, `You must provide a value for ...`, `Please select an account.`, placement errors) → [application-scope-misconfigured](./playbooks/application-scope-misconfigured.md).
 - Raw `ConnectionHttpException` (or `Office365Exception` with the identical IS-status message) from a trigger → [email-trigger-connection-event-failure](./playbooks/email-trigger-connection-event-failure.md).
+- A `ConnectionHttpException` message embedding a **`CNS…` error code** (the Connection Service API error body `{ "code": "CNS…", "message": "…", "traceId": "…" }`, from the token fetch or trigger event lookup) → route by the exact code via the [CNS error-code reference](../../products/integration-service/cns-error-codes-reference.md): `CNS1008` connection not authorized (re-authenticate), `CNS1006`/`CNS1049` connection deleted / personal-workspace, `CNS1045` missing folder permission (names the permission), `CNS2xxx` service-side. The CNS code is more precise than the HTTP status class — prefer it when present.
 - `The specified object was not found in the store.` / `Item ... doesn't belong to the targeted mailbox` / 404 on a message ID → [mail-message-not-found](./playbooks/mail-message-not-found.md).
 - `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` → [mail-invalid-odata-query](./playbooks/mail-invalid-odata-query.md).
 - `File does not exist: <path>` / `ErrorInvalidRecipients` / `ErrorSendAsDenied` / `ErrorMessageSizeExceeded` on a send/forward/reply → [send-mail-rejected](./playbooks/send-mail-rejected.md).

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/authentication-token-invalid.md

@@ -42,7 +42,7 @@ What can cause it:
 
 ## Resolution
 
-- **If the token is expired/invalid:** re-authenticate the connection — re-run the interactive login, refresh/reconnect the Integration Service connection, or rotate and update the app secret/certificate that has expired.
+- **If the token is expired/invalid:** re-authenticate the connection — re-run the interactive login, refresh/reconnect the Integration Service connection, or rotate and update the app secret/certificate that has expired. When the auth mode is an Integration Service connection, the runtime token fetch is a Connection Service call — a failure body with code `CNS1008` (connection not in authorized state) confirms the connection needs re-authentication, and other `CNS…` codes route via the [CNS error-code reference](../../../products/integration-service/cns-error-codes-reference.md).
 - **If `AADSTS65001` / consent:** have an administrator grant admin consent for the permissions the app registration requests.
 - **If another `AADSTS` credential code:** correct the Application ID / Tenant / secret / certificate to match the app registration.
 - **If an interactive sign-in timed out in an unattended / Agent / StudioPro context** (`The client did not complete the authentication after <N> seconds ... Authentication type: InteractiveToken.`): the root cause is the **auth mode**, not the timeout value. Switch the Microsoft 365 Scope to **app-only authentication (App ID + Secret or Certificate)** — the client-credentials flow needs no human — or route the connection through **Integration Service** (which refreshes the token). Selecting/binding an account only helps an *attended* desktop where a person completes the sign-in; it does **not** make Interactive Token viable for unattended/Agent runs, and raising the timeout won't help when no one is there to complete the prompt.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/email-trigger-connection-event-failure.md

@@ -33,7 +33,7 @@ What to look for:
 
 ## Investigation
 
-1. Extract the HTTP status / error detail embedded in the exception message — it identifies the failing layer (401/403 auth, 404 connection missing, 5xx service). **The status class is decisive and outranks any narrative** — activity display names, process names, or comments describing the connection as "dead"/"broken" are workflow text, not evidence; never confirm or eliminate a cause from them.
+1. Extract the HTTP status / error detail embedded in the exception message — it identifies the failing layer (401/403 auth, 404 connection missing, 5xx service). **The status class is decisive and outranks any narrative** — activity display names, process names, or comments describing the connection as "dead"/"broken" are workflow text, not evidence; never confirm or eliminate a cause from them. If the detail embeds a **`CNS…` code**, that outranks the status class — route it via the [CNS error-code reference](../../../products/integration-service/cns-error-codes-reference.md) (`CNS1008` re-authenticate · `CNS1006`/`CNS1049` deleted / personal-workspace · `CNS1045` folder permission, the message names which · `CNS1075` connector not deployed, non-retryable · `CNS2xxx` service-side).
 2. Identify the connection the trigger uses (trigger's connection property or binding) and verify it exists and is **Authorized**: `uip is connections list --folder-key <folder> --output json`, then check the `state` / `isDefault` fields for the connector. **If this bare probe itself returns 5xx** (e.g. `HTTP 503: no healthy upstream`) the connection service is down — that is the operative cause for the fault regardless of the trigger's own connection configuration (a bad/placeholder connection ID cannot produce a 503 on a list call). Report any suspicious connection configuration (e.g. unset/all-zeros ConnectionId in trace spans) as a separate secondary finding to fix before the trigger can work once the service recovers.
 3. Confirm the connection is available in the Orchestrator folder the trigger's process runs in — a connection created in a different folder does not resolve at runtime.
 4. Distinguish run type: Studio debug (sample lookup) vs. deployed trigger run (live event). If only debug fails and the connection is healthy, re-check the filter/folder configuration instead.
@@ -41,5 +41,5 @@ What to look for:
 ## Resolution
 
 - **If 401/403-class status (token rejected, consent revoked):** re-authenticate the connection in Integration Service (Orchestrator → Integration Service → Connections → reconnect). Follow the Integration Service playbook `connection-auth-expired.md` for the full path.
-- **If 404-class status (connection not found):** the connection was deleted or is not shared with the job's folder — recreate it or move/share it into the correct folder, then reselect it on the trigger and republish.
+- **If 404-class status (connection not found):** the connection was deleted or is not shared with the job's folder — recreate it or move/share it into the correct folder, then reselect it on the trigger and republish. A `CNS1049` "personal folder" detail means the connection lives in someone's personal workspace — move it to a shared folder rather than recreating.
 - **If 5xx-class status:** transient Integration Service failure — retry; if it persists across retries over a sustained period, escalate as a service incident.

package/skills/uipath-troubleshoot/references/activity-packages/system-activities/playbooks/get-asset-activity-bug-silent-failure.md

@@ -11,7 +11,7 @@ A `Get Asset` or `Get Orchestrator Asset` activity completes without throwing an
 What this looks like:
 - Activity completes successfully (no exception in job traces)
 - Output variable contains null, zero, or empty string instead of the expected asset value
-- Downstream logic fails because it receives an unexpected empty value
+- Downstream logic fails because it receives an unexpected empty value — typically a `System.NullReferenceException` ("Object reference not set to an instance of an object") thrown by a consumer of the asset value, NOT by the Get Asset activity itself. Plain null in user workflow logic with no Get Asset upstream → runtime-exceptions null-reference-exception.md
 
 What can cause it:
 - Activity was copy-pasted from another sequence — copy-paste retains internal state from the original activity

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/application-not-found.md

@@ -72,7 +72,7 @@ Fix: precede the scope with `NCheckAppState` waiting for the main-window selecto
 
 ## Post-presentation actions
 
-This resolution path is **interactive** — every recommended fix above ends in a file edit (XAML property change, adding a new activity before the scope, adjusting timeouts). The orchestrator MUST call `AskUserQuestion` at the end of the troubleshooting to (a) print the exact property/file/line to be modified and the before → after value, and (b) ask the user whether to apply the fix. Do not write to the user's source files until that question is answered with explicit approval.
+This resolution path is **interactive** — every recommended fix above ends in a file edit (XAML property change, adding a new activity before the scope, adjusting timeouts). You MUST call `AskUserQuestion` at the end of the troubleshooting to (a) print the exact property/file/line to be modified and the before → after value, and (b) ask the user whether to apply the fix. Do not write to the user's source files until that question is answered with explicit approval.
 
 Rules the agent MUST follow:
 
@@ -80,5 +80,5 @@ Rules the agent MUST follow:
 2. **Never bundle "gather input" with "apply fix" in a single option.** Any option that contains phrasing like "I'll … apply / edit / write the change" alongside an input request must be split into two steps: gather the input, then surface the specific diff and confirm separately.
 3. **Surface the diff before asking.** The apply-fix question must include the file path, the activity `IdRef` or line number, the current value, and the proposed value. Vague approvals ("fix the scope") are not enough — show the concrete edit.
 4. **One question per fix, not one for the whole branch.** If multiple files need editing (e.g., XAML plus an Object Repository `.content` file mirror), list every file in the question or ask file-by-file. Do not silently propagate the same substitution to side-channel files.
-5. The presenter must emit a `## Post-presentation actions` block in its output declaring this interactive step; the orchestrator must execute it before closing the investigation. Do not collapse this into a generic "fix the OpenMode" recommendation — the apply-fix prompt is part of the documented resolution.
+5. Execute this interactive step per `references/presenting.md` § Interactive resolutions before closing the investigation. Do not collapse this into a generic "fix the OpenMode" recommendation — the apply-fix prompt is part of the documented resolution.
 6. **If you cannot obtain interactive approval, do not edit.** When the approval prompt is unavailable or errors in the current environment, fall back to presenting the diff as a recommendation and stop — leave the apply step to the user. Never write to a source file without explicit approval, even when the approval mechanism is unavailable. A recommendation-only close is always acceptable; a silent edit is not.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/click-coordinate-off-screen.md

@@ -89,9 +89,9 @@ What can cause it — four distinct mechanisms, each fits a different XAML patte
          Resolution and surface the ambiguity to the user.
    ```
 
-   **Host-geometry data.** Do NOT fabricate or assume the host's display geometry. The `uip` CLI does not currently expose monitor/resolution metadata for a robot host (`or machines list` returns registration metadata only — no `Resolution`, `VirtualScreenRectangle`, or `Monitors` fields). If you cannot derive the runtime virtual-screen rectangle from a verified source (job logs, traces, an attached screenshot, a Healing-Agent capture), STOP and write `.local/investigations/needs_input.json` per `agents/shared.md` § "Requesting User Input". Ask for the host's display configuration with concrete option ranges (e.g., `1920x1080`, `2560x1440`, `3840x2160`, `multi-monitor with primary <X>x<Y>`). Do NOT default to any "typical" value — choosing the wrong sub-cause picks the wrong fix.
+   **Host-geometry data.** Do NOT fabricate or assume the host's display geometry. The `uip` CLI does not currently expose monitor/resolution metadata for a robot host (`or machines list` returns registration metadata only — no `Resolution`, `VirtualScreenRectangle`, or `Monitors` fields). If you cannot derive the runtime virtual-screen rectangle from a verified source (job logs, traces, an attached screenshot, a Healing-Agent capture), STOP and ask via `AskUserQuestion`. Ask for the host's display configuration with concrete option ranges (e.g., `1920x1080`, `2560x1440`, `3840x2160`, `multi-monitor with primary <X>x<Y>`). Do NOT default to any "typical" value — choosing the wrong sub-cause picks the wrong fix.
 
-   **When the orchestrator re-spawns you with the user's answer**, continue from this step: re-run the decision tree using the new data and pick the matching sub-cause. Do NOT stop at "answer received" — the answer is an input to *complete* your verdict, not the verdict itself. Record the diff in your evidence file and set the hypothesis status before returning to the orchestrator.
+   **When the user answers**, continue from this step: re-run the decision tree using the new data and pick the matching sub-cause. Do NOT stop at "answer received" — the answer is an input to *complete* your verdict, not the verdict itself. Record the diff and the resulting verdict in notes.md before presenting.
 
 6. **Confirm Healing could not relocate.** Read job-get → `JobInputArguments` / process settings for `AutopilotForRobots.HealingEnabled`. Confirm the job-error log contains `Healing agent is disabled for the current job.` or the equivalent. If Healing was enabled but produced no fix, switch to `no-recovery-data.md`.
 

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

@@ -25,9 +25,9 @@ What can cause it:
 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
+5. **If wrong-page scope is plausible, locate the project source.** First check the working directory top level for the project (`project.json` plus the workflow file named in the activity stack) — if present, treat it as the project source and go to step 6. One top-level listing is the only discovery permitted — do not recursively scan, glob for extensions, or assume paths elsewhere. Only if absent, ask the user for the project source path via `AskUserQuestion`, explaining that the parent scope wrapper's configuration needs to be inspected against the failing activity's target. If the user declines or has no path: skip step 6 and mark the wrong-page-scope hypothesis as unverified.
+6. **Once the project source is located**, inspect the parent scope wrapper (`NApplicationCard`, `Attach Browser`, `Open Application`, etc.):
+   - Read the workflow file named in the exception's activity stack from the project source
    - 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`)