@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connector-remote-exception.md

@@ -0,0 +1,31 @@
+---
+confidence: medium
+---
+
+# Connector Activity — RemoteException (Ipc / CoreIpc)
+
+## Context
+
+What this looks like — robot exception `UiPath.Ipc.RemoteException` or `UiPath.CoreIpc.RemoteException` (the two are the same phenomenon across two IPC library generations). Connector activities execute **out-of-process** in the connector executor; an unhandled fault in that process crosses the IPC boundary wrapped in `RemoteException`. There is **no `DAP-` code** — the operative signal is the **unwrapped inner message** after the `RemoteException:` prefix (follow `--->` chains to the innermost text).
+
+For connector activities (`ConnectorActivity`, `ConnectorTriggerActivity`) the inner message is typically one of:
+- **Token / auth:** `Could not obtain access token. (...)`, `Could not obtain user token. ...`, `invalid_grant`, `The Client ID or Client Secret is incorrect.`, `1 or more scope requested are not robot scopes.`, `The user is no longer a member of the organization.`
+- **Transport:** `An existing connection was forcibly closed by the remote host.`, `Unable to read data from the transport connection`, `The SSL connection could not be established`, `The operation has timed out.`, `The request was canceled due to the configured HttpClient.Timeout`.
+- **Downstream HTTP:** `Response status code does not indicate success: 404 (Not Found).` / `502 (Bad Gateway).` / `503 (Service Unavailable).`
+
+> **Different cause — do NOT apply this playbook.** `RemoteException` is a generic robot↔executor wrapper, not Integration-Service-specific. The same class wraps UI Automation, Computer Vision (`Cloud Vision API ... disabled`), `Could not find a process named '<x>' in folder '<workspace>'` (robot/folder assignment), assembly-load failures (`Could not load file or assembly ...`), and missing-file errors. Only treat it as a connector failure when the faulted activity is a connector activity (`*.IntegrationService.Activities.*` / `Connector*`) **and** the inner message is auth/transport/HTTP as above. If the inner message is process-not-found, assembly-load, or a non-connector activity, route to the matching Orchestrator / runtime playbook instead.
+
+## Investigation
+
+1. **Unwrap to the innermost message.** Strip the `RemoteException:` prefix and follow every `--->` to the deepest inner exception. Classify it: token/auth, transport, or downstream HTTP. Match on that, not on the `RemoteException` class name.
+2. **Confirm the faulted activity is a connector activity** (triage's activity name). If not, this playbook does not apply — see the disambiguation note above.
+3. For **auth** inner messages: `uip is connections ping <connection-id>` — confirm the connection's token state; see [connection-auth-expired.md](./connection-auth-expired.md).
+4. For **transport / 5xx / 503**: check whether the failure is transient (succeeds on retry) or persistent. Transient transport/5xx is an external-service or platform availability issue, not a workflow defect.
+5. For **404**: the referenced resource (record/endpoint) does not exist in the external service — verify the ID/path the operation used.
+
+## Resolution
+
+- **Token / auth inner message:** re-authenticate the connection (`uip is connections edit <connection-id>` or the UI). If `invalid_grant` / revoked / scope errors, re-authorize the app in the external service first. If `user is no longer a member of the organization`, the connection's owning identity must be replaced.
+- **Transport / SSL / timeout / 5xx / 503:** treat as transient — retry the job. If persistent, check the external service's status and any network egress / proxy between the robot and the service; raise the activity timeout only after ruling out a real outage.
+- **404 (downstream):** correct the resource identifier the operation references; confirm the record exists in the external service.
+- **Inner message is non-connector** (process-not-found, assembly-load, missing file): stop — this is not an Integration Service failure; investigate under the relevant Orchestrator / runtime playbook.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connector-runtime-exception.md

@@ -0,0 +1,40 @@
+---
+confidence: high
+---
+
+# Connector Activity — RuntimeException (DAP-RT)
+
+## Context
+
+What this looks like — robot exception `UiPath.IntegrationService.Activities.Runtime.Exceptions.RuntimeException` with a `DAP-RT-` error code. Unlike GeneralException (connection-resolution), these fault during activity setup or the connector operation itself. The code maps to an exact cause:
+
+| Code | Verbatim message | Cause |
+|------|------------------|-------|
+| `DAP-RT-1002` | `Connection ID is empty.` | No connection bound to the activity — the `ConnectionId` was never set (or its binding/asset resolved to empty at runtime). |
+| `DAP-RT-1003` | `<field> field is required.` | A required input field of the connector operation is empty/null at runtime. |
+| `DAP-RT-1052` | `Trigger activity could not find any matches.` | `ConnectorTriggerActivity` sample/debug lookup returned zero events — the trigger object has no matching records to pull. |
+| `DAP-RT-1101` | `Status code: BadRequest.` / `Status code: NotFound.` (and other HTTP statuses) — accompanied by a `ProviderMessage` / `ProviderErrorCode` block with the downstream provider's own error | The connector operation reached the external service, which rejected the request (bad input, missing/renamed resource, unsupported operation). |
+
+Which activities produce this:
+- **ConnectorActivity** — DAP-RT-1002, DAP-RT-1003, DAP-RT-1101.
+- **ConnectorTriggerActivity** — DAP-RT-1052 (and DAP-RT-1002 if the trigger has no connection).
+
+What can cause it:
+- **1002:** activity dropped its connection binding (common after copy/paste between projects, or a deleted asset feeding `ConnectionId`).
+- **1003:** an input argument is empty because an upstream variable was null, or a mandatory field was left unmapped.
+- **1052:** the configured trigger object genuinely has no events in the sampled window — usually expected during setup/debug, not a defect.
+- **1101:** input doesn't match the operation's schema; referenced record doesn't exist in the external service; the external API changed/deprecated the endpoint.
+
+## Investigation
+
+1. **Read the exact `DAP-RT` code from the job log / Info** — it routes the rest. For 1002/1003/1052 the cause is known from the code alone; for 1101 read the full inner detail (status + body).
+2. For **1002**: if source is available, inspect the activity's `ConnectionId` binding in the workflow (XAML/code) and check whether it points at an asset/variable that resolved empty.
+3. For **1003**: identify which field — the message names it. Trace the upstream value.
+4. For **1101**: read the `ProviderMessage` / `ProviderErrorCode` block in the error first — it carries the external provider's own error (e.g. `providerErrorCode - 404`, `reason=notFound`, `location=fileId`), which names the exact failing parameter and HTTP status. Then `uip is resources describe <connector-key> <object>` to confirm required fields and supported operations; compare against what the activity sent. Check whether the referenced record/file exists.
+
+## Resolution
+
+- **DAP-RT-1002:** set/repair the activity's connection binding so a valid connection ID resolves at runtime; verify any asset feeding `ConnectionId` exists in the runner's folder.
+- **DAP-RT-1003:** populate the named required field, or guard the upstream value so it is never null.
+- **DAP-RT-1052:** for `ConnectorTriggerActivity`, this is usually benign — confirm the trigger object actually has events; if events are expected but absent, see [trigger-not-firing.md](./trigger-not-firing.md).
+- **DAP-RT-1101:** this is the activity-package form of an operation error — follow [operation-failed.md](./operation-failed.md) (fix input to match the schema, verify the resource exists, or update for an API change).

package/skills/uipath-troubleshoot/references/products/integration-service/summary.md

@@ -8,3 +8,8 @@
 | Connection Authentication Expired | High | Connection was working but now fails — OAuth token expired or revoked | [connection-auth-expired.md](./playbooks/connection-auth-expired.md) |
 | Trigger Not Firing | Medium | IS trigger configured but events not starting jobs/instances — subscription, permissions, or event mismatch | [trigger-not-firing.md](./playbooks/trigger-not-firing.md) |
 | Operation Failed | Medium | IS activity returns error during execution — bad request, unsupported method, or input validation | [operation-failed.md](./playbooks/operation-failed.md) |
+| Connector Activity — GeneralException (DAP-GE) | High | `UiPath.IntegrationService.Activities.Runtime.Exceptions.GeneralException` with `DAP-GE-3000` (`Failed to retrieve connection …` — invalid/no-access, `Connections.View` permission, or Bad Gateway) or `DAP-GE-3005` (`Connection is disabled. Please enable the connection to continue.`). Connection-resolution failure in ConnectorActivity / ConnectorHttpActivity / ConnectorTriggerActivity. | [connector-general-exception.md](./playbooks/connector-general-exception.md) |
+| Connector Activity — RuntimeException (DAP-RT) | High | `UiPath.IntegrationService.Activities.Runtime.Exceptions.RuntimeException` with `DAP-RT-1002` (`Connection ID is empty.`), `DAP-RT-1003` (`<field> field is required.`), `DAP-RT-1052` (`Trigger activity could not find any matches.`), or `DAP-RT-1101` (`Status code: BadRequest./NotFound.`). Binding/input/trigger/operation failure in ConnectorActivity / ConnectorTriggerActivity. | [connector-runtime-exception.md](./playbooks/connector-runtime-exception.md) |
+| Connector Activity — RemoteException (IPC) | Medium | `UiPath.Ipc.RemoteException` / `UiPath.CoreIpc.RemoteException` — out-of-process connector executor fault crossing the IPC boundary (no DAP code). Match on the **unwrapped inner message**: token/auth, transport, or downstream HTTP (404/502/503). Disambiguate from non-connector RemoteExceptions. | [connector-remote-exception.md](./playbooks/connector-remote-exception.md) |
+| Connector Activity — NullReferenceException | Medium | `System.NullReferenceException` on/after a connector activity — typically enumerating a null connector output (`ForEach` over `SWEntities.*_List`), an unmapped output, or a null required input. | [connector-null-reference.md](./playbooks/connector-null-reference.md) |
+| Connector Activity — AggregateException | Low | `System.AggregateException` on a connector activity — async connector fault(s). The real cause is `InnerExceptions[0]`; unwrap and re-classify. | [connector-aggregate-exception.md](./playbooks/connector-aggregate-exception.md) |

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

@@ -4,9 +4,10 @@
 
 Before using any fetched data, verify it matches the user's reported problem:
 
+- **Maestro instance key == Orchestrator job key for ProcessOrchestration jobs.** When the user's reported entity is a job whose `RuntimeType` is `ProcessOrchestration`, the job IS the Maestro process instance — the GUID on the Orchestrator job is also the Maestro instance ID. ALWAYS use that key when running `uip maestro <type> instance <verb>` commands. **Do NOT use `ParentJobKey`** — that field, when present, points at the parent Orchestrator job, not the Maestro instance. Using `ParentJobKey` against a Maestro instance command returns empty results that are silently misread as "the instance doesn't exist", which then propagates a wrong root cause downstream.
 - **Process/Solution** — the BPMN process name and solution match what the user reported
 - **Instance** — the process instance ID matches the specific execution the user is investigating
-- **Folder** — data comes from the correct Orchestrator folder (permissions, triggers, and jobs are folder-scoped)
+- **Folder** — data comes from the correct Orchestrator folder (permissions, triggers, and jobs are folder-scoped). The Maestro instance lives in the same folder as the Orchestrator job — NOT in any "personal workspace" or parent-job folder. Use the folder key resolved on the Orchestrator job, not a workspace key.
 - **Time window** — timestamps fall within the relevant period the user described
 - **Child Jobs** — if investigating a service task, verify the child job belongs to the correct parent instance. Always check the child job's **error message and final state** — the child's failure reason is often the actual root cause, not the parent's error code. Search for child jobs in all states (Faulted, Stopped, Successful, Running), not just the expected state.
 

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

@@ -1,10 +1,80 @@
 # Orchestrator Investigation Guide
 
+## Output Capture Pattern
+
+Every `uip` data-gathering command below assumes two patterns to keep the agent's context lean AND preserve an audit trail:
+
+1. **Filter at the source with `--output-filter`** — only pull the fields you actually need. Do NOT fetch the full response and truncate the output with `[:3000]` or similar post-hoc slicing — that silently drops information.
+2. **Save AND inspect in one call with `| tee`** — pipe the filtered response through `tee` to `.local/investigations/raw/<command>.json`. The response is visible in the tool result for immediate use AND saved on disk for the hypothesis-tester to re-read later. **Run `mkdir -p .local/investigations/raw` once before the first fetch — `tee` does not create the directory and will otherwise drop the file silently.**
+
+Reference shape:
+
+```
+uip or jobs list --folder-key <key> --state Faulted \
+  --output json \
+  --output-filter '[].{Key:Key,State:State,StartTime:StartTime,ReleaseName:ReleaseName}' \
+  | tee .local/investigations/raw/triage-jobs-list.json
+```
+
+**Filter-failure fallback.** If `--output-filter '<jsonpath>'` returns an empty result, an error, or a shape the agent cannot interpret (likely cause: a field name in the documented filter has drifted from the current CLI response schema), retry the SAME command ONCE without `--output-filter` to see the actual response shape. Use that unfiltered response for the current call, and note the stale filter in your evidence summary so the discrepancy gets fixed in the guide. Do NOT silently swallow filter errors — they mean the documented filter is stale.
+
+Anti-patterns — do NOT do these:
+
+- `uip <cmd> --output json > file.json` — redirect alone hides stdout; the agent then needs an extra turn running `python -c "json.load(...)"` just to see what it fetched.
+- `uip <cmd> --output json | head -c 3000` or any byte/character slice — truncation silently drops fields that may be required by the playbook downstream.
+- Fetching the unfiltered full response when only 2–3 fields are needed — bloats the agent's context and the cache-read budget on every subsequent turn.
+- Inventing JSONpath field names on the fly. Use only the filter expressions documented in this guide for each command. If a documented filter fails, apply the filter-failure fallback above — do NOT guess different field names.
+
+If the CLI's `--output-filter` cannot express the shape you need, see `scripts/` for skill-provided filter helpers, OR fetch with a minimal field set first and only re-fetch with more fields when a specific gap forces it.
+
 ## Data Correlation
 
 Before fetching ANY job, queue, or asset data, resolve identity first:
 
-1. **Folder** — resolve the folder key (GUID). All Orchestrator data is folder-scoped. Use `uip or folders list` to find all accessible folders (Personal, Solution, and Standard) — the default view is scoped to the current user. Use `uip or folders list --all` only when you need every folder in the tenant (filtering and sorting flags require `--all`). Use `uip or folders get <key-or-path>` to confirm details. If the folder is inaccessible, STOP — nothing else will be valid without it. **After resolving the folder, verify it contains the target entity** (e.g., run `uip or jobs get <key>` or a scoped query for the expected process/queue). If the target entity is not found in the resolved folder, try other folders from `folders list` before continuing. Do NOT proceed with a folder that returns empty results for the target entity.
+1. **Folder** — resolve the folder key (GUID). All Orchestrator data is folder-scoped, so the folder MUST be pinned before any data fetch.
+
+   **STOP. Before running ANY `uip` command, check the user's prompt for a folder name. The answer is binary:**
+
+   - **(A) User named a folder explicitly in the prompt** (e.g., "the failed job in *Shared*", "in *PurchaseOrderProcessing* folder") → continue with step A below.
+   - **(B) User did NOT name a folder** (e.g., "investigate my last failed job", "my automation broke") → **STOP and ask the user. Do NOT run `uip or jobs list` looking for the failed job. Do NOT iterate over folder keys hoping to find it. Do NOT infer the folder from `project.json` — that is a hint to surface in the ask, not a selector to commit on.** Go directly to step B below.
+
+   The above is non-negotiable. The single most expensive triage failure mode is `jobs list` enumeration against arbitrary folders trying to "find" a job whose folder is unspecified — it burns 20–40 turns and an extra subagent dispatch before the orchestrator's sanity gate catches the wrong pick. Asking the user is 2 turns. Always cheaper.
+
+   ---
+
+   **Step A — User named a folder.** Resolve its key:
+   ```
+   uip or folders list --output json \
+     --output-filter "[?DisplayName=='<name>'].{Key:Key,FullyQualifiedName:FullyQualifiedName}" \
+     | tee .local/investigations/raw/triage-folders-list.json
+   ```
+   If the result is empty (no folder with that name), write `needs_input.json` listing the available folders and asking the user to confirm the correct one. Do NOT guess. Proceed once the key is resolved.
+
+   ---
+
+   **Step B — User did NOT name a folder. Ask, do not search.**
+
+   1. Run folders list ONCE to get candidates:
+      ```
+      uip or folders list --output json \
+        --output-filter "[].{Key:Key,DisplayName:DisplayName,FullyQualifiedName:FullyQualifiedName}" \
+        | tee .local/investigations/raw/triage-folders-list.json
+      ```
+   2. Write `needs_input.json` with the candidate folder names as `options`. If `project.json` exists in the working directory and its `name` matches one of the folders, put that folder FIRST in the options list with the label `"<folder> (your current project)"` — surface the hint, do not select for the user. Ask: *"Which folder is the failing job in?"*
+   3. Return to the orchestrator. Do NOT continue with any data fetch.
+   4. On re-spawn with the user's answer, record the chosen folder in `state.json` and proceed to step 2 (Process).
+
+   **Bounded fallback** — applies ONLY when the user explicitly answers step B.3 with "I don't know" / "no preference" / equivalent. Run ONCE without folder filter, pick the most-recent, record the folder, proceed:
+   ```
+   uip or jobs list --state <state> --output json \
+     --output-filter "[].{Key:Key,State:State,StartTime:StartTime,FolderName:FolderName}" \
+     | tee .local/investigations/raw/triage-jobs-cross-folder.json
+   ```
+   `<state>` is the state the user named (`Faulted` for "failed", `Pending` for "stuck", etc.). If this returns nothing, report and stop — do NOT relax the state filter and do NOT retry against per-folder keys.
+
+   ---
+
+   Use `uip or folders get <key-or-path>` to confirm details if needed. If the folder is inaccessible, STOP — nothing else will be valid without it.
 2. **Process** — identify the process name (from user input, working directory `project.json`, or package name). All subsequent queries filter by this process.
 3. **Time window** — establish the relevant period from the user's report.
 
@@ -22,12 +92,32 @@ If data doesn't match: **discard it**. Do NOT fetch details for jobs or items fr
 
 ## Job Data Bundle
 
-For every job under investigation, gather these in order. Write each to `raw/` immediately.
-
-1. **Job details** — `uip or jobs get <key>` — state, input/output arguments, timing, machine info, error details
-2. **Job logs** — `uip or jobs logs <key>` — robot execution logs, newest-first. Folder is inferred from the job key. Use `--level Error` to quickly find errors. Use `--limit` to control how many entries (default 50)
-3. **Job history** — `uip or jobs history <key>` — job state transition history (timestamps for each state change: Pending → Running → Faulted). Useful for identifying delays and lifecycle issues.
-4. **Job traces** — `uip or jobs traces <key>` — job execution traces (activity states, variable snapshots, execution path). Available for all job types.
+For every job under investigation, gather these in order. Follow the Output Capture Pattern above — pipe through `tee` and filter at the source.
+
+1. **Job details** — state, input/output arguments, timing, machine info, error details
+   ```
+   uip or jobs get <key> --output json \
+     --output-filter '{Key:Key,State:State,StartTime:StartTime,EndTime:EndTime,Info:Info,JobError:JobError,InputArguments:InputArguments,OutputArguments:OutputArguments}' \
+     | tee .local/investigations/raw/triage-job-get.json
+   ```
+2. **Job logs** — robot execution logs, newest-first. Folder is inferred from the job key. Use `--level Error` to find errors quickly. `--limit` controls entry count (default 50).
+   ```
+   uip or jobs logs <key> --level Error --output json \
+     --output-filter '[].{Level:Level,TimeStamp:TimeStamp,Message:Message}' \
+     | tee .local/investigations/raw/triage-job-logs.json
+   ```
+3. **Job history** — state transition timestamps (Pending → Running → Faulted). Useful for delays and lifecycle issues.
+   ```
+   uip or jobs history <key> --output json \
+     --output-filter '[].{State:State,CreationTime:CreationTime,Reason:Reason}' \
+     | tee .local/investigations/raw/triage-job-history.json
+   ```
+4. **Job traces** — execution traces (activity states, variable snapshots, execution path). Available for all job types.
+   ```
+   uip or jobs traces <key> --output json \
+     | tee .local/investigations/raw/triage-job-traces.json
+   ```
+   Traces are dense; consider filtering by activity name or error attribute when re-fetching for hypothesis testing.
 
 This is the baseline. Domain-specific data gathering builds on it — see the investigation guide for each matched domain (UI Automation, Integration Service, Maestro) for additional steps after the baseline.
 
@@ -47,15 +137,20 @@ For comparison investigations (e.g., queue-items-failing playbook), also gather
 
 ## Finding Related Jobs
 
-When investigating service tasks, child jobs, or multi-job processes, use `jobs list` to find related jobs:
+When investigating service tasks, child jobs, or multi-job processes, use `jobs list` with `--state` ALWAYS set when the user named a state in their prompt ("failed" → `--state Faulted`, "stuck" → `--state Pending`, etc.). Filter at the source:
 
 ```
-uip or jobs list --folder-key <folder-key> --process-name <name> --created-after <start> --created-before <end> --output json
+uip or jobs list --folder-key <folder-key> --state Faulted \
+  --process-name <name> \
+  --created-after <start> --created-before <end> \
+  --output json \
+  --output-filter '[].{Key:Key,State:State,StartTime:StartTime,ReleaseName:ReleaseName}' \
+  | tee .local/investigations/raw/triage-jobs-list.json
 ```
 
 Key flags (all optional, but `--folder-key` or `--folder-path` is required):
 - `--folder-key <key>` — folder GUID (required, or use `--folder-path`)
-- `--state <state>` — filter by state: Pending, Running, Successful, Faulted, Stopped, Stopping, Suspended, Resumed, Terminating
+- `--state <state>` — filter by state: Pending, Running, Successful, Faulted, Stopped, Stopping, Suspended, Resumed, Terminating. **Required when the user named a state in their prompt** — never `jobs list` without a state filter when the prompt says "failed" / "stuck" / "cancelled", or you will fetch unrelated jobs and pick the wrong one.
 - `--process-name <name>` — filter by process name (contains match)
 - `--created-after <datetime>` / `--created-before <datetime>` — narrow to a time window (ISO 8601)
 

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/job-faulted-logon-failure.md

@@ -66,7 +66,7 @@ Map the branch identified in Investigation to the fix:
 
 - **Branch 1 — Session configuration mismatch:**
   - Option A: Set "Login to Console" to true on the robot user (Orchestrator → Tenant → Users → user → Access Rules → Advanced Robot Options), so the Robot creates its own console session when no one is logged in.
-  - Option B: Ensure a user is logged into the machine before jobs run.
+  - Option B: Ensure a robot is logged into the machine before jobs run.
   - Prevention: For processes with `requiresUserInteraction: true`, default Login to Console to true.
 - **Branch 2 — Account locked:**
   - Have a domain admin unlock the account in Active Directory (AD Users & Computers → user → Account → "Unlock account", or `Unlock-ADAccount -Identity <user>`).

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

@@ -29,7 +29,9 @@ Agentic orchestration platform built on Orchestrator. BPMN-based process design
 
 ## Integration Service
 
-Connector platform for third-party integrations (Salesforce, Outlook, SAP, Slack, etc.). Manages OAuth connections, exposes activities for automations and BPMN processes, and provides event-based triggers. Issues here involve connection failures, expired authentication, triggers not firing, and operation errors. Connection errors from Integration Service often surface through Maestro or Orchestrator as the calling product.
+Connector platform for third-party integrations (Salesforce, Outlook, SAP, Slack, etc.). Manages OAuth connections, exposes activities for automations and BPMN processes, and provides event-based triggers. Issues here involve connection failures, expired authentication, triggers not firing, and operation errors. Connection errors from Integration Service often surface through Maestro or Orchestrator as the calling product. Also covers the runtime exceptions thrown by the connector activities (`ConnectorActivity`, `ConnectorTriggerActivity`, `ConnectorHttpActivity`): `GeneralException`/`RuntimeException` with `DAP-GE-*`/`DAP-RT-*` codes, and `UiPath.Ipc`/`UiPath.CoreIpc` `RemoteException`.
+
+Namespaces: `UiPath.IntegrationService.Activities`, `UiPath.IntegrationService.Activities.Runtime.Exceptions`
 
 CLI: `uip is --help`
 
@@ -62,6 +64,15 @@ Namespaces: `UiPath.UIAutomationNext.Activities`, `UiPath.UIAutomation.Activitie
 - [activity-packages/ui-automation/overview.md](./activity-packages/ui-automation/overview.md) — Package overview, selector mechanics, exception types, and dependencies
 - [activity-packages/ui-automation/summary.md](./activity-packages/ui-automation/summary.md) — All playbooks for UI Automation issues
 
+## Computer Vision (CV) Activities
+
+Activities that target UI elements by visual analysis of a screenshot instead of selectors — for virtualized/Citrix/RDP, image-based, and remote desktops. Every CV activity runs inside a CV Screen Scope (`CVScope`) that screenshots the target window; a CV server (cloud or local) plus an OCR engine detects elements, the descriptor (target + anchors) is matched, and the action fires at the matched coordinates. Issues here involve element-not-found / descriptor-match failures, invalid descriptors, table cell-targeting errors, scroll-search failures, CV server auth/throttling/network errors, scope setup failures, post-find action failures, and silent/false results (`ContinueOnError` / `InRegion` suppression).
+
+Namespaces: `UiPath.CV.Activities` (exceptions: `UiPath.CV`)
+
+- [activity-packages/cv-activities/overview.md](./activity-packages/cv-activities/overview.md) — Package overview, CV targeting mechanics, exception types, and common failure patterns
+- [activity-packages/cv-activities/summary.md](./activity-packages/cv-activities/summary.md) — All playbooks for Computer Vision Activities issues
+
 ## System Activities
 
 Core workflow activities from `UiPath.System.Activities` that interact with Orchestrator resources at runtime — asset retrieval, credential lookup, queue operations, and storage buckets. Issues here involve asset-not-found errors, permission denied, folder scope mismatches, external vault failures, and package version bugs.
@@ -100,13 +111,58 @@ Namespaces: `UiPath.MicrosoftOffice365.Activities`
 
 ## Excel Activities
 
-Activities for automating Microsoft Excel on Windows via COM interop (modern `Excel Process Scope` activities) and OpenXML file access (legacy workbook activities). Issues here involve `Invoke VBA` failures — Trust Center security blocks, malformed external code files, entry method name mismatches, parameter marshaling errors, and COM interop instability (`0x80010100 RPC_E_SYS_CALL_FAILED` and related HRESULTs).
+Desktop Excel activities from `UiPath.Excel.Activities` — read, write, delete, and manipulate `.xlsx` / `.xls` workbooks, run VBA macros (`Invoke VBA`, `Execute Macro`), and look up ranges on the host filesystem via Excel COM (Excel installed) or the OpenXML provider (Excel not required). Issues here involve workbooks locked by other processes, sheet names not found, range parsing failures, provider-specific parsing errors on heavily formatted or sensitivity-labeled files, Trust Center macro blocks, entry-method / parameter marshaling errors, COM-interop instability (`0x80010100 RPC_E_SYS_CALL_FAILED` and related HRESULTs), and Application Scope / Use Excel File container failures. For cloud Excel via Microsoft Graph, see Microsoft Office 365 Activities above.
 
 Namespaces: `UiPath.Excel.Activities`
 
-- [activity-packages/excel-activities/overview.md](./activity-packages/excel-activities/overview.md) — Package overview, `Invoke VBA` execution model, and common failure patterns
+- [activity-packages/excel-activities/overview.md](./activity-packages/excel-activities/overview.md) — Package overview, providers, scopes, execution models, and common failure patterns
 - [activity-packages/excel-activities/summary.md](./activity-packages/excel-activities/summary.md) — All playbooks for Excel Activities issues
 
+## Word Activities
+
+Activities for automating Microsoft Word documents on Windows. Operations run inside a `Use Word File` (`WordProcessScope`) or classic `Word Application Scope` container and drive a real WINWORD.EXE through Office Interop (COM), requiring desktop Word on the execution host. Issues span package-wide COM / host failures common to all Word activities (type library / class not registered `0x8002801D` / `0x80040154` / `REGDB_E_CLASSNOTREG`, bitness mismatch, Word busy/blocked `0x8001010A`, `WINWORD.EXE` crashing mid-operation with `RPC_E_WRONG_THREAD` `0x8001010E`); `Word Application Scope` failures (corrupted-file errors, indefinite hangs on background modal dialogs, "cannot create unknown type" load errors, document-path resolution); and `Add Picture` (`WordAddImage`)-specific failures (activity placed outside a Word scope, insertion target text/bookmark not found, invalid image path / unusable image input).
+
+Namespaces: `UiPath.Word.Activities`
+
+- [activity-packages/word-activities/overview.md](./activity-packages/word-activities/overview.md) — Package overview, execution models, and common failure patterns
+- [activity-packages/word-activities/summary.md](./activity-packages/word-activities/summary.md) — All playbooks for Word Activities issues
+
+## Python Activities
+
+Activities for invoking Python from a workflow. `UiPath.Python.Activities` does not run Python in-process — `Python Scope` launches a separate Python host process and marshals objects over an IPC pipe; `Load Python Script` / `Run Python Script` / `Invoke Python Method` / `Get Python Object` call into that host. Issues here involve `Pipe is broken` / `Error invoking Python method` (the out-of-process host died — a pip module missing from the scope's interpreter, an unhandled exception, a hard `sys.exit`, or stdout flooding), `The specified Python path is not valid` (`Path` points at `python.exe` instead of the install folder, or the `WindowsApps\python` Store alias), `One or more errors occurred` / engine-init failures (`Target` bitness, `Version`, or `Library path` mismatch, or a missing .NET Desktop Runtime), and scripts that run but read/write the wrong files (relative paths resolving against the robot's per-package `WorkingFolder`).
+
+Namespaces: `UiPath.Python.Activities`
+
+- [activity-packages/python-activities/overview.md](./activity-packages/python-activities/overview.md) — Package overview, out-of-process execution model, and common failure patterns
+- [activity-packages/python-activities/summary.md](./activity-packages/python-activities/summary.md) — All playbooks for Python Activities issues
+
+## Database Activities
+
+Activities for querying and modifying relational databases over ADO.NET (SQL Server, Oracle, MySQL, ODBC, OLE DB). A `DatabaseConnection` opened by `Connect to Database` / `Start Transaction` is consumed by `Execute Query`, `Execute Non Query`, `Run Command`, and the bulk/insert activities. Issues here involve null/out-of-scope connections, provider/driver mismatches after Windows-Legacy → Windows migration, SQL syntax / unsafe concatenation, query text in the connection-string field, command timeouts, `0xE0434352` CLR crashes, and using the wrong activity for the statement type.
+
+Namespaces: `UiPath.Database.Activities`
+
+- [activity-packages/database-activities/overview.md](./activity-packages/database-activities/overview.md) — Package overview, connection model, key activities, and common failure patterns
+- [activity-packages/database-activities/summary.md](./activity-packages/database-activities/summary.md) — All playbooks for Database Activities issues
+
+## Python Activities
+
+Activities for running Python code from a UiPath workflow via the `UiPath.Python.Activities` package. A `Python Scope` initializes an out-of-process Python engine (bound through Python.NET) that its child activities — `Load Python Script`, `Invoke Python Method`, `Get Python Object` — run against. Issues here involve engine-initialization failures (invalid `Path`, `Target` bitness mismatch, `Library path` missing for Python > 3.9 on Windows, unsupported Python version, missing .NET Desktop Runtime 6+), script load/import errors (`ModuleNotFoundError`, top-level syntax/exception, unresolved local imports), and hangs / oversized return data. Engine-config and module errors often surface only on the robot host — the scope uses the interpreter at `Path` and Windows environment variables, not the IDE's venv/conda env.
+
+Namespaces: `UiPath.Python.Activities`
+
+- [activity-packages/python-activities/overview.md](./activity-packages/python-activities/overview.md) — Package overview, Python Scope execution model and properties, and common failure patterns
+- [activity-packages/python-activities/summary.md](./activity-packages/python-activities/summary.md) — All playbooks for Python Activities issues
+
+## Web Activities
+
+Activities for outbound HTTP calls and payload deserialization. `HttpClient` (legacy, RestSharp) and `NetHttpRequest` (modern, `System.Net.Http`) issue HTTP requests; `DeserializeJson`, `DeserializeJsonArray`, and `DeserializeXml` parse a string into a typed object / `JArray` / `XDocument`. Issues here involve HTTP request failures (`System.Net.WebException` — status / DNS / connection / SSL), request timeouts (`System.TimeoutException`), null request inputs (`System.NullReferenceException`), modern-activity faults wrapped in `System.AggregateException`, malformed JSON/XML payloads (`Newtonsoft.Json.JsonReaderException` / `System.Xml.XmlException`), JSON type mismatches (`Newtonsoft.Json.JsonSerializationException`), and null/empty payloads (`System.ArgumentNullException`). These activities propagate raw framework exceptions — the faulted activity class + exception class is the discriminator. A malformed/null deserialize fault is frequently a symptom of an upstream HTTP call.
+
+Namespaces: `UiPath.Web.Activities`
+
+- [activity-packages/web-activities/overview.md](./activity-packages/web-activities/overview.md) — Package overview, activity families, and common failure patterns
+- [activity-packages/web-activities/summary.md](./activity-packages/web-activities/summary.md) — All playbooks for Web Activities issues
+
 
 ## Playbooks
 

package/skills/uipath-troubleshoot/schemas/evidence.schema.md

@@ -59,6 +59,54 @@ Each evidence file:
 }
 ```
 
+## Signals (triage-initial.json only)
+
+`evidence/triage-initial.json` carries a top-level `signals` array. Signals are the structured inventory of discrete facts triage extracted from gathered data. They are the unified input to playbook matching, hypothesis generation, and hypothesis testing.
+
+```json
+{
+  "signals": [
+    {
+      "name": "exception_class",
+      "value": "System.NullReferenceException",
+      "category": "exception",
+      "source": "raw/triage-job-logs.json"
+    },
+    {
+      "name": "package_version",
+      "value": "UiPath.System.Activities 22.10.5",
+      "category": "package_version",
+      "source": "raw/triage-job-traces.json"
+    },
+    {
+      "name": "asset_exists",
+      "value": true,
+      "category": "entity_state",
+      "source": "raw/triage-resource-assets-list.json"
+    }
+  ]
+}
+```
+
+### Fields
+
+- `name` — short identifier for the signal (e.g., `exception_class`, `error_code`, `asset_exists`, `package_version`). Snake_case, descriptive.
+- `value` — observed value. String, number, or boolean. For boolean signals like `asset_exists`, `true` means "asset is present"; `false` means "asset is absent".
+- `category` — one of: `exception | error_code | http_status | activity_label | entity_state | package_version | runtime_type | error_fragment | cross_product_ref | folder_context`. Use the closest match; do not invent new categories without need.
+- `source` — relative path to the raw file the signal was extracted from. The signal MUST be traceable back to actual observed data.
+
+### Producers and consumers
+
+- **Triage** produces signals while executing plan data-fetch steps. Each fetched response is scanned for signal-worthy facts and entries are appended to `signals`. Triage step E (match playbooks) iterates this array, not the raw files.
+- **Hypothesis generator** reads `signals` to inform what hypotheses to draft. Each generated hypothesis records which signals supported it (see `schemas/hypotheses.schema.md` → `signals_supporting`).
+- **Hypothesis tester** reads `signals` BEFORE its test plan. For each `to_confirm` / `to_eliminate` item, the tester checks whether a signal already resolves it. If yes, the corresponding plan step is `status: skipped` with the signal name in `purpose` — no re-fetch.
+
+### Rules
+
+- One signal per discrete fact. Do NOT combine multiple facts into one signal (`exception_class_and_message` is two signals, not one).
+- Never overwrite or reconcile a signal in place — one `name` = one observed fact. If two raw sources disagree, that is NOT a forbidden state: record each observation as its own signal with a distinct `name` and let the matcher / downstream agents resolve the conflict. The only thing disallowed is mutating an existing signal (see immutability below).
+- Signals are immutable once written. New evidence appends new signals; existing signals don't get rewritten.
+
 ## Rules
 
 - **Raw data MUST be written to `.local/investigations/raw/` immediately** — write the full response to a raw file BEFORE summarizing

package/skills/uipath-troubleshoot/schemas/hypotheses.schema.md

@@ -4,7 +4,7 @@ File: `.local/investigations/hypotheses.json`
 
 Created by: Hypothesis Generator sub-agent
 Read by: Hypothesis Tester sub-agent, orchestrator
-Updated by: Hypothesis Tester (status, evidence), Orchestrator (root cause flag)
+Updated by: Hypothesis Tester (status, evidence, is_root_cause, open_gaps), Orchestrator (may override root-cause flag; writes resolution)
 
 ## Structure
 
@@ -25,8 +25,21 @@ Updated by: Hypothesis Tester (status, evidence), Orchestrator (root cause flag)
         "to_confirm": ["what evidence would prove this"],
         "to_eliminate": ["what evidence would disprove this"]
       },
+      "signals_supporting": ["names of signals from triage-initial.json that support this hypothesis"],
+      "signals_contradicting": ["names of signals that would contradict — populated by tester if any fire"],
+      "test_plan": [
+        {
+          "n": 1,
+          "action": "uip <subcommand> --output json | tee raw/H1-<file>.json",
+          "purpose": "fetches a to_confirm or to_eliminate item",
+          "feeds": "evidence/H1-<source>.json",
+          "revise_if": "observed-field condition (empty if unconditional)",
+          "status": "pending"
+        }
+      ],
       "evidence_refs": ["evidence/H1-cli-data.json"],
       "evidence_summary": "What was actually discovered during testing",
+      "open_gaps": ["what is still missing — unmet testable prerequisites, undocumented-command gaps, out-of-band prerequisites, or a runtime-evidence contradiction"],
       "resolution": null
     }
   ],
@@ -44,13 +57,15 @@ Updated by: Hypothesis Tester (status, evidence), Orchestrator (root cause flag)
 
 ## Rules
 
-- Hypothesis Generator creates/appends hypotheses
-- Hypothesis Tester updates: `status`, `evidence_refs`, `evidence_summary`
-- Orchestrator updates: `is_root_cause` (true/false) after tester confirms
-- Orchestrator updates: `resolution` field for confirmed root causes
+- Hypothesis Generator creates/appends hypotheses, populates `signals_supporting` from the triage `signals` inventory (each hypothesis cites the signals that drove it), leaves `test_plan: []` and `signals_contradicting: []` — the tester writes those.
+- Hypothesis Tester reads triage's `signals` array BEFORE writing `test_plan`. Any `to_confirm` / `to_eliminate` item already resolved by an existing signal becomes a `status: skipped` plan step with the signal name in `purpose`. After execution, the tester updates: `status`, `evidence_refs`, `evidence_summary`, and appends any new contradicting signals to `signals_contradicting`. See `schemas/state.schema.md` § Plan for plan-step structure.
+- Hypothesis Tester writes `open_gaps` on `inconclusive`/`confirmed` (unmet testable prerequisites, undocumented-command gaps, out-of-band prerequisites, runtime-evidence contradictions). `status: confirmed` may carry `open_gaps` only for out-of-band items that do not block confirmation.
+- Hypothesis Tester sets `is_root_cause` on confirm (`true` = evidence explains WHY, `false` = shows only WHAT). Orchestrator may override per its upstream-cause gate.
+- Orchestrator updates: `resolution` field for confirmed root causes, after the depth-check verdict (the depth-verifier reads the playbook's `## Resolution`, not this field)
 - Never remove eliminated hypotheses — they prevent retesting
 - `parent` links sub-hypotheses to the confirmed symptom they're deepening
 - `generation_context` tells the generator what happened before (for re-invocation)
 - When deepening: orchestrator sets `generation_context.trigger: "deepening"` and `generation_context.parent_hypothesis` to the ID of the confirmed symptom before re-invoking the generator
-- `source`: `playbook` for playbook-derived, `docsai` for documentation-derived, `evidence` for evidence-derived
-- When high-confidence playbooks exist, the generator produces ONLY high-confidence hypotheses (fast path). If all high-confidence hypotheses are eliminated, the orchestrator re-invokes the generator with `trigger: "scope_adjustment"` to produce from remaining medium/low playbooks. When a high-confidence hypothesis is confirmed, the orchestrator skips to resolution.
+- `source`: `playbook` for playbook-derived, `docsai` for documentation-derived, `evidence` for evidence-derived. This is the hypothesis-origin tag — distinct from the evidence-file `source` enum (`uip_cli | docsai | playbook | user | source_code`) in `evidence.schema.md`.
+- `test_plan` step `status` enum is `pending | done | skipped` (see `state.schema.md` § Plan)
+- The generator drafts hypotheses for every matched playbook — all confidence levels — in a single round (see `shared.md` § Single-round coverage rule), ranked by `signal_match_count`. `trigger: "scope_adjustment"` re-invocation is reserved for producing additional hypotheses from docsai once every playbook-derived hypothesis is eliminated. When a high-confidence hypothesis is confirmed, the orchestrator skips the lower-ranked remainder (subject to the co-equal-roots guard).

package/skills/uipath-troubleshoot/schemas/scope-check.schema.md

@@ -9,7 +9,7 @@ Read by: Orchestrator
 
 ```json
 {
-  "checked_after": "triage | hypotheses | test",
+  "checked_after": "triage | test",
   "current_domains": ["orchestrator"],
   "missing_domains": [],
   "unnecessary_domains": [],

package/skills/uipath-troubleshoot/schemas/state.schema.md

@@ -12,7 +12,7 @@ Updated by: Orchestrator (phase transitions)
 {
   "id": "inv-YYYY-MM-DD-NNN",
   "created_at": "ISO8601 timestamp",
-  "phase": "triage | hypotheses | test | evaluate | deepen | resolution | complete",
+  "phase": "triage | hypotheses | test | evaluate | deepen | depth_check | resolution | complete",
   "scope": {
     "level": "platform | product | feature | process | activity",
     "domain": ["orchestrator", "maestro", "integration-service", "ui-automation"],
@@ -32,17 +32,37 @@ Updated by: Orchestrator (phase transitions)
   "matched_playbooks": [
     {
       "confidence": "low",
-      "path": "references/products/orchestrator/playbooks/job-stuck.md"
+      "path": "references/products/maestro/playbooks/bpmn-job-stuck.md",
+      "signal_match_count": 3,
+      "signals_matched": ["job state is Running", "runtime type is ProcessOrchestration", "no incident error code"]
     },
     {
       "confidence": "low",
-      "path": "references/products/maestro/playbooks/bpmn-job-stuck.md"
+      "path": "references/products/orchestrator/playbooks/job-stuck.md",
+      "signal_match_count": 2,
+      "signals_matched": ["job state is Running", "no error logs present"]
+    }
+  ],
+  "eliminated_playbooks": [
+    {
+      "path": "references/activity-packages/system-activities/playbooks/get-asset-not-found.md",
+      "contradicting_signal": "playbook signature requires asset absent / HTTP 404 / error code 1002; evidence shows asset exists in the resolved folder"
     }
   ],
   "requirements": {
     "folder_id": 2157426,
     "source_code_path": "/path/to/project"
-  }
+  },
+  "plan": [
+    {
+      "n": 1,
+      "action": "uip <subcommand> --output json | tee raw/<file>.json",
+      "purpose": "what signal the step yields",
+      "feeds": "which downstream step / playbook / decision the result routes to",
+      "revise_if": "observed-field condition that mutates the remaining plan (empty if unconditional)",
+      "status": "pending"
+    }
+  ]
 }
 ```
 
@@ -52,7 +72,62 @@ Resolved by triage. Always includes the generic guide (`references/investigation
 
 ## Matched Playbooks
 
-Resolved by triage. Full paths to every playbook that matches the symptoms, with confidence level (high/medium/low). High-confidence playbooks have a specific error match and known cause. Medium have concrete troubleshooting steps. Low provide general context. The generator uses confidence to decide how many hypotheses to produce per playbook.
+Resolved by triage. Full paths to every playbook that matches the symptoms, with per-playbook signal-match data.
+
+Fields per entry:
+
+- `path` — relative path to the playbook from the skill root.
+- `confidence` — the playbook's frontmatter confidence (`high | medium | low`). **This is a cap on how decisively the playbook can pin a root cause when matched** — `high` means the playbook describes a specific error with a known cause; `medium` means concrete troubleshooting steps but the conclusion depends on inspection of uncertain fields; `low` provides general context. **Confidence is not a ranking input — see signal_match_count.** Do NOT modify the frontmatter confidence.
+- `signal_match_count` — integer count of how many distinct signature signals from the playbook's `## Context` and `## Investigation` sections the gathered evidence actually satisfies. A signal is a discrete fact: an exception class, a specific error code, a verbatim error fragment, an entity-state assertion, a package version, an activity-instance label, etc.
+- `signals_matched` — array of short labels naming each signal that was satisfied (audit trail for `signal_match_count`).
+
+**Ranking.** Matched playbooks are ordered by `signal_match_count` DESCENDING — highest specificity first, regardless of frontmatter confidence. A `medium`-confidence playbook with 3 matched signals ranks above a `high`-confidence playbook with 1 matched signal. The hypothesis generator drafts H1 from the top-ranked playbook, H2 from the second-ranked, etc. Ties on signal count are broken by frontmatter confidence (`high > medium > low`).
+
+**Three categories of evidence-vs-playbook relationship:**
+
+- **Positively supported** (`signal_match_count >= 1`) → list in `matched_playbooks`.
+- **Silent** (evidence neither supports nor contradicts any of the playbook's signals) → do NOT list. The playbook is uninformed by the available evidence; it cannot be tested productively until more data exists.
+- **Contradicted** (evidence directly disproves at least one CORE signal of the playbook signature) → do NOT list in `matched_playbooks`; instead record in `eliminated_playbooks` with the contradicting evidence. The hypothesis generator will not draft hypotheses from these.
+
+A "core signal" is one named in the playbook's `## Context` or `## Investigation` as a required precondition for the cause to apply (e.g., "asset is absent / HTTP 404", "robot has no matching credentials", "connection ID returns 'invalid'"). Surface-level signals shared across siblings (e.g., "Get Asset activity") are NOT core signals — they're descriptors, not preconditions.
+
+## Eliminated Playbooks
+
+Playbooks whose signature was contradicted by triage evidence. Each entry records:
+
+- `path` — playbook path.
+- `contradicting_signal` — short sentence naming the playbook's required signal AND the contradicting evidence (e.g., "playbook requires asset absent; evidence shows asset exists in folder").
+
+The hypothesis generator MUST exclude these from consideration. The depth-verifier MUST NOT confirm a hypothesis that maps to an eliminated playbook.
+
+**Why count over confidence.** Multiple playbooks can match the same surface signal (e.g., "Get Asset activity failed" appears in five distinct get-asset playbooks at frontmatter `high`). Ranking purely on frontmatter confidence then surfaces 5-way false positives at HIGH. Counting actual signal hits per playbook discriminates between them: the one whose specific signature is most fully satisfied by the evidence wins. Frontmatter confidence still caps the root-cause certainty downstream (`high` matches can fast-path; `medium`/`low` require deeper testing) — but it does not decide ordering.
+
+## Plan
+
+The investigation plan is the agent's single, growing record of everything it intends to do. Triage starts with a one-step plan (classify the user's message) and appends steps as data arrives. **The plan IS the procedure** — there is no pre-plan or post-plan phase; every action the agent takes is a plan step that is recorded, executed, and audited.
+
+Field semantics:
+
+- `n` — step order (1-indexed; numbering grows as steps are appended).
+- `action` — what the agent will do at this step. Action shapes:
+  - **Tool call** — an exact CLI command (with output capture), or `read <path>` for a file read.
+  - **User interaction** — `ask user: <question>` (free-text) or `ask user (select): <opt> | <opt> | …` (multi-choice surfaced via `AskUserQuestion`).
+  - **Reasoning** — a named decision the agent records without calling a tool: `classify (system, entity) from user message`, `re-evaluate scope against gathered evidence`, `match playbooks against in-scope summaries`, etc. The agent's reasoning + result is captured in `purpose` / step output.
+- `purpose` — the specific signal or decision the step yields (one short phrase).
+- `feeds` — which downstream step or decision consumes the result.
+- `revise_if` — observed-field condition that mutates the remaining plan (add/drop steps). Empty if the step is unconditional.
+- `status` — `pending | done | skipped`.
+
+**The plan is revisable.** After each step the agent evaluates `revise_if` against the observed data, then appends/modifies remaining steps. If the just-completed step yields information that requires new steps not anticipated by any `revise_if` (a genuine discovery), the agent appends them with a one-line `purpose` before executing. The agent runs ONLY plan steps — never a freestyle command.
+
+**Boundaries on what can appear in a plan:**
+
+- No open-ended enumeration steps (no "search every folder", no tenant-wide sweep). Locate passes are single bounded calls with at least one filter (state, time window, or named anchor).
+- No `get <unknown-id>` actions for entities that have not been located. A `get` step requires the id to be resolved by an earlier step.
+- No undocumented commands. Every tool-call step must run a command documented in the matched investigation guide or the matched playbook's `## Investigation` section.
+- A single Pass 2 extension is permitted when the initial pass yields weak matches; a Pass 3 is not.
+
+The plan structure is reusable: any sub-agent that gathers data (triage, hypothesis-tester) writes a plan of its own. For the hypothesis-tester, the plan is stored on the hypothesis itself (`hypotheses.json` → per-hypothesis `test_plan`), not on `state.json`.
 
 ## Requirements
 
@@ -64,7 +139,7 @@ Generic key-value store for data gathered during the investigation. Any agent ca
 ## Rules
 
 - Triage sub-agent creates this file and resolves investigation guides, matched playbooks, and requirements
-- Other agents read paths from `state.json` — they do NOT browse `references/` themselves (exception: presenter discovers presentation guides directly from domain folders)
+- Other agents read paths from `state.json` — they do NOT browse `references/` themselves (exception: triage, scope-checker, depth-verifier, and presenter browse references — see `shared.md` invariant 3)
 - Orchestrator updates `phase` as the investigation progresses
 - Any agent can read `requirements`; triage and orchestrator write to it
 - The `scope` may be updated by the orchestrator when scope adjustment occurs