@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-rpa/references/xaml/flowchart-guide.md

@@ -0,0 +1,113 @@
+# Flowchart Guide
+
+Node vocabulary, structure, and wiring for `<Flowchart>` workflows. Related references: XAML anatomy → [xaml-basics-and-rules.md](xaml-basics-and-rules.md); layout + ViewState → [canvas-layout-guide.md § 3](canvas-layout-guide.md#3-flowchart-layout); node registration full rules → [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming).
+
+## When to Use a Flowchart
+
+Branching logic with multiple decision points, loops, and back-edges. Best when the flow is a graph rather than a straight sequence. For straight-line steps use a `Sequence`; for state-driven processes use a State Machine; for BPMN-style event-driven long waits use a Long Running Workflow (ProcessDiagram).
+
+## Node Vocabulary
+
+| Node | Purpose | Successor wiring |
+|------|---------|------------------|
+| `FlowStep` | Wraps **exactly one** activity (which may be a container). The unit of work. | `FlowStep.Next` → one node |
+| `FlowDecision` | Boolean branch. `Condition` plus `True`/`False` targets. | `FlowDecision.True` / `.False` → one node each |
+| `FlowSwitch<T>` | Multi-way branch keyed by an expression. | `Default` plus one target per case |
+
+A `FlowStep` wraps one activity. If that activity is a container (`Sequence`, `NApplicationCard`, `TryCatch`), its children stay nested and are NOT separate nodes. See [canvas-layout-guide.md § What Counts as a Node](canvas-layout-guide.md#3-flowchart-layout).
+
+## Structure & Wiring
+
+**Rule:** every `FlowStep`/`FlowDecision`/`FlowSwitch` is a **direct child of `<Flowchart>`** with an `x:Name`. Links between nodes are made with `<x:Reference>__ReferenceIDn</x:Reference>` inside property elements (`Flowchart.StartNode`, `FlowStep.Next`, `FlowDecision.True`/`.False`) — never by physically nesting one node inside another.
+
+```xml
+<Flowchart DisplayName="My Flowchart" sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <x:Reference>__ReferenceID1</x:Reference>
+    </FlowStep.Next>
+  </FlowStep>
+  <FlowDecision x:Name="__ReferenceID1">
+    <FlowDecision.Condition>
+      <CSharpValue x:TypeArguments="x:Boolean">condition</CSharpValue>
+    </FlowDecision.Condition>
+    <FlowDecision.True>
+      <x:Reference>__ReferenceID0</x:Reference>
+    </FlowDecision.True>
+    <!-- FlowDecision.False omitted = end of flow -->
+  </FlowDecision>
+</Flowchart>
+```
+
+`__ReferenceID` values must be unique across the whole file. When adding nodes, use a number higher than any existing one.
+
+## Node Registration
+
+Only nodes in the `Flowchart.Nodes` collection render — and that collection is built from the **direct children** of `<Flowchart>`. A node that is not a direct child is never registered, so the designer does not draw it, regardless of ViewState.
+
+Two cases:
+
+1. **Direct children** of `<Flowchart>` — already registered. Do NOT also add a trailing `<x:Reference>`.
+2. **Inline definitions** inside a property element (e.g., a `FlowStep` written inside `<FlowDecision.True>`) — MUST add a trailing `<x:Reference>` entry as a direct child of `<Flowchart>` to register them.
+
+Full correct/wrong examples for inline registration: [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming).
+
+### Forbidden — nested FlowStep chains
+
+Do NOT build the flow by physically nesting each `FlowStep` inside the previous one's `<FlowStep.Next>` (a deep chain with only the first node under `<Flowchart.StartNode>`). Nested-only steps never enter `Flowchart.Nodes`, so the designer renders almost nothing — invisible regardless of ViewState. Wire successors by reference and keep every step a direct child.
+
+**Correct** — each step a direct child, linked by reference:
+```xml
+<Flowchart sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <x:Reference>__ReferenceID1</x:Reference>
+    </FlowStep.Next>
+  </FlowStep>
+  <FlowStep x:Name="__ReferenceID1">          <!-- direct child — in Flowchart.Nodes -->
+    <ui:LogMessage DisplayName="Step 2" />
+  </FlowStep>
+</Flowchart>
+```
+
+**Wrong** — Step 2 nested inside Step 1's `.Next`; `Flowchart.Nodes` holds only Step 1, so Step 2 never renders:
+```xml
+<Flowchart sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <FlowStep>                              <!-- WRONG — nested, not registered -->
+        <ui:LogMessage DisplayName="Step 2" />
+      </FlowStep>
+    </FlowStep.Next>
+  </FlowStep>
+</Flowchart>
+```
+
+### No Orphan Nodes
+
+Every node except the start must be reachable: referenced by `Flowchart.StartNode`, a `FlowStep.Next`, or a decision/switch branch. A `FlowStep` with no incoming reference and no `FlowStep.Next` is an orphan — it renders as a disconnected box and is almost always a leftover. Do not generate them.
+
+## Condition Expressions
+
+`FlowDecision.Condition` and `FlowSwitch` expressions follow the project's expression language:
+
+- **C# projects:** `<CSharpValue x:TypeArguments="x:Boolean">condition</CSharpValue>`
+- **VB projects:** `<mva:VisualBasicValue x:TypeArguments="x:Boolean" ExpressionText="condition" />`
+
+## Layout & ViewState
+
+ViewState is **mandatory** for Flowcharts — without per-node `ShapeLocation`+`ShapeSize`, Studio stacks every node at (0,0) and they overlap into what looks like a single node (Studio does NOT auto-arrange on open). ViewState positions a node **only after** it is registered in `Flowchart.Nodes` — structure first, then coordinates.
+
+Coordinate system, node sizes, connector routing, and full ViewState recipes: [canvas-layout-guide.md § 3](canvas-layout-guide.md#3-flowchart-layout). See also SKILL.md Rule 20.

package/skills/uipath-rpa/references/xaml/xaml-basics-and-rules.md

@@ -74,7 +74,7 @@ Linear, step-by-step execution. Best for straightforward processes.
 ### Flowchart
 Branching logic with decision nodes. Best for complex decision flows.
 
-**Key pattern:** All FlowStep/FlowDecision/FlowSwitch nodes are direct children of `<Flowchart>`. Use `<x:Reference>` inside property elements (`Flowchart.StartNode`, `FlowStep.Next`, `FlowDecision.True/False`) to cross-reference nodes.
+**Key pattern:** All FlowStep/FlowDecision/FlowSwitch nodes are direct children of `<Flowchart>`; wire them via `<x:Reference>` inside property elements (`Flowchart.StartNode`, `FlowStep.Next`, `FlowDecision.True/False`). NEVER nest one `FlowStep` inside another's `<FlowStep.Next>` — nested-only steps are absent from `Flowchart.Nodes` and won't render.
 
 ```xml
 <Flowchart DisplayName="My Flowchart" sap2010:WorkflowViewState.IdRef="Flowchart_1">
@@ -99,11 +99,7 @@ Branching logic with decision nodes. Best for complex decision flows.
 </Flowchart>
 ```
 
-**Node registration:** If a node is defined inline within a property element (e.g., inside `FlowStep.Next`) instead of as a direct Flowchart child, it needs a trailing `<x:Reference>` entry as a direct child of `<Flowchart>`. See [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming) for details.
-
-**Expression language:** VB projects use `<mva:VisualBasicValue x:TypeArguments="x:Boolean" ExpressionText="condition" />` instead of `<CSharpValue>`.
-
-**ViewState is needed** for usable Flowchart layout. See [canvas-layout-guide.md § Flowchart Layout](canvas-layout-guide.md#3-flowchart-layout) for coordinate systems, sizes, and recipes.
+Node vocabulary, structure & wiring rules, the forbidden nested-chain pattern, node registration, condition expressions (VB/C#), and layout: [flowchart-guide.md](flowchart-guide.md). Layout coordinates and ViewState recipes: [canvas-layout-guide.md § Flowchart Layout](canvas-layout-guide.md#3-flowchart-layout).
 
 ### State Machine
 State-based workflow with transitions. Best for long-running processes with distinct states (e.g., REFramework).
@@ -204,7 +200,7 @@ ViewState controls how activities appear in the visual designer. Rules differ by
 
 **Sequences:** ViewState is optional — Studio auto-manages `IsExpanded` state. No coordinates needed.
 
-**Flowcharts, State Machines, Long Running Workflows:** ViewState determines node positions on the 2D canvas. Without it, Studio stacks all nodes at (0,0) — producing an unusable overlapping layout. Studio will auto-arrange when the file is opened, but the result may not match your intended layout.
+**Flowcharts, State Machines, Long Running Workflows:** ViewState is **mandatory** — it determines node positions on the 2D canvas. Without it, Studio stacks every node at (0,0): they overlap into what looks like **a single node**. Studio does **not** auto-arrange on open — the stacked layout persists until a user manually triggers Auto Arrange. Always generate ViewState for these workflow types.
 
 **When editing existing files:**
 - Do NOT modify the global `<sap2010:WorkflowViewState.ViewStateManager>` section — it can corrupt the designer layout
@@ -212,10 +208,10 @@ ViewState controls how activities appear in the visual designer. Rules differ by
 - When adding new nodes to a Flowchart/StateMachine, read existing node positions first to avoid overlap
 
 **When generating new Flowchart/StateMachine/ProcessDiagram files:**
-- Generate ViewState (ShapeLocation, ShapeSize, ConnectorLocation) for every node to produce a usable layout
+- Generate ViewState for every node to produce a usable layout: `ShapeLocation` + `ShapeSize` are required; `ConnectorLocation` is optional (Studio auto-routes connectors from node positions)
 - See [canvas-layout-guide.md](canvas-layout-guide.md) for coordinate systems, standard sizes, and layout recipes
 
-> **Why the distinction?** The `uip rpa` commands communicate with Studio via IPC, and Studio regenerates layout when opening files. However, auto-arrange produces arbitrary layouts. If you need a specific visual structure (e.g., decision tree, loop pattern), generate ViewState explicitly.
+> **Why the distinction?** Sequences stack children vertically on their own, so coordinates are unnecessary. Flowcharts, State Machines, and ProcessDiagrams are 2D canvases with no implicit ordering — Studio cannot place nodes it has no coordinates for, so it leaves them all at (0,0). The result reads as one overlapping node. Generate ViewState for every node so the workflow renders as separate, connected nodes.
 
 ### Preserve xmlns Declarations
 Never remove existing `xmlns` attributes from the root `<Activity>` element. Only add new ones as needed. Removing a namespace declaration that is referenced anywhere in the file will cause validation errors.

package/skills/uipath-solution/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uipath-solution
-description: "Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/pack/publish/deploy/activate/upload, project add|import|remove, resource refresh|add|remove|edit. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For coded-app deploy→uipath-coded-apps."
-when_to_use: "User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution'. Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy."
+description: "Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/restore/pack/publish/deploy/activate/upload, project add|import|remove, resource refresh|add|remove|edit. Also DIAGNOSE solution-lifecycle failures: pack/publish/deploy/activate errors, stale or missing bindings, unimported/unset/unresolved resources, deploy error codes (e.g. `[1009] Invalid argument 'Value'`), publish name+version/processKey collisions, and `uip solution` 'unknown command' after the new→init rename. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For coded-app deploy→uipath-coded-apps."
+when_to_use: "User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution'. Also fires to DIAGNOSE solution problems: 'why did my solution pack/publish/deploy fail', 'pack ships stale/old bindings', 'my resource edit didn't take effect', 'refresh imported 0 bindings', deploy fails '[1009] Invalid argument Value', publish 'name+version / processKey collision', 'uip solution new: unknown command', 'coded app missing from the .uipx / not packed'. (Solution build-time/CLI faults belong here; faulted Orchestrator JOBS at runtime → uipath-troubleshoot.) Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy."
 ---
 
 # UiPath Solution — `uip solution` lifecycle
@@ -62,13 +62,16 @@ The typical lifecycle for a UiPath Solution:
 ```
 1. init / project add  → Create solution, register projects (.uipx + resources/solution_folder/)
 2. resource refresh    → Sync bundled artefacts and debug overwrites with cloud state
-3. pack                → Produce deployable .zip package
-4. login               → uip login (if not already authenticated)
-5. publish             → Upload packed solution to UiPath
-6. deploy run          → Promote to Orchestrator (auto-activates by default)
-7. (optional) activate → Use --skip-activate on deploy, then activate explicitly
+3. (optional) restore  → Resolve NuGet deps in place (incl. authenticated Orchestrator feeds); login first
+4. pack                → Produce deployable .zip package
+5. login               → uip login (if not already authenticated)
+6. publish             → Upload packed solution to UiPath
+7. deploy run          → Promote to Orchestrator (auto-activates by default)
+8. (optional) activate → Use --skip-activate on deploy, then activate explicitly
 ```
 
+> **`restore` is an optimization, not a requirement.** `pack` restores dependencies internally, so a separate `restore` step is only useful when you want deps resolved up front — most often in CI (`login → restore → pack`) to fail fast on a missing feed before the heavier pack runs. `restore` takes a `<solutionPath>` only (solution dir with a `.uipx`, or a `.uis` file), resolves deps in place, and does **not** produce a package. It needs an authenticated session to reach private Orchestrator feeds, so run `uip login` before it.
+
 > **Coded apps in the project list deploy in parallel, not through `uip solution`.** Coded-app projects (Coded Web Apps and Coded Action Apps) have no `project.uiproj` / `project.json` and are NOT registered via `uip solution project add`. For each coded-app project in the unified list, run `uip codedapp publish` / `uip codedapp deploy` independently — the rest of the solution still goes through steps 1-7 above. See `uipath-coded-apps` for the coded-app lifecycle.
 
 Two distinct distribution paths from the same source:
@@ -85,7 +88,7 @@ This skill is the terminal step of an SDD-driven build: after `uipath-planner` p
 |------|---------|
 | [Solution Overview](references/solution-overview.md) | What a Solution is, `.uipx` manifest, file structure, lifecycle diagram, command tree |
 | [Develop a Solution](references/develop-solution.md) | `uip solution init / project add / import / remove / resource refresh / resource add / resource remove / resource edit`; field-tested gotchas |
-| [Pack and Deploy](references/pack-and-deploy.md) | `pack / publish / deploy run`, deploy configs, CI/CD pipeline patterns |
+| [Pack and Deploy](references/pack-and-deploy.md) | `restore / pack / publish / deploy run`, deploy configs, CI/CD pipeline patterns |
 | [Activate and Manage](references/activate-and-manage.md) | `deploy activate / status / uninstall`, environment management |
 | [Scenarios Index](references/scenarios.md) | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |
 

package/skills/uipath-solution/references/pack-and-deploy.md

@@ -20,7 +20,8 @@ Pack a solution into a deployable package, publish to the feed, and deploy to Or
 
 ```mermaid
 graph LR
-    A[solution pack] --> B[solution publish]
+    R["(optional)<br/>solution restore"] --> A[solution pack]
+    A --> B[solution publish]
     B --> C[deploy config get]
     C --> D[config set / link]
     D --> E["deploy run<br/>(auto-activate by default)"]
@@ -32,6 +33,21 @@ graph LR
 
 ---
 
+## Step 0 (Optional): Restore Dependencies
+
+Resolve NuGet dependencies for every project in the solution, in place, using the authenticated session:
+
+```bash
+uip solution restore ./MySolution --output json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<solutionPath>` | Solution directory (containing a `.uipx`) or a `.uis` file (required) | -- |
+| `--login-validity <minutes>` | Minimum minutes left on the access token before the CLI refreshes it before restore starts | 10 |
+
+`restore` resolves dependencies on disk and does **not** produce a package. It needs an authenticated session (`uip login`) to reach private Orchestrator feeds. `pack` already restores internally, so this step is an **optimization, not a requirement** — its value is in CI, where running `login → restore → pack` fails fast on a missing or unreachable feed before the heavier pack step runs. Skip it for a plain local pack.
+
 ## Step 1: Pack the Solution
 
 Build a deployable .zip from a solution directory:
@@ -245,6 +261,7 @@ jobs:
       - uses: actions/checkout@v4
       - run: npm install -g @uipath/cli
       - run: uip login --client-id "${{ secrets.UIPATH_CLIENT_ID }}" --client-secret "${{ secrets.UIPATH_CLIENT_SECRET }}" --tenant "${{ secrets.UIPATH_TENANT }}" --output json
+      - run: uip solution restore ./MySolution --output json   # optional: fail fast on a missing feed before pack
       - run: uip solution pack ./MySolution ./output --version "1.0.${{ github.run_number }}" --output json
       - run: uip solution publish ./output/MySolution.*.zip --output json
       - run: uip solution deploy run -n "MySolution-${{ github.run_number }}" --package-name "MySolution" --package-version "1.0.${{ github.run_number }}" --folder-name "MySolution" --config-file deploy-config.json --output json

package/skills/uipath-solution/references/solution-overview.md

@@ -42,6 +42,8 @@ MySolution/
 
 > **Coded apps are not registered in `.uipx`.** UiPath Coded Web Apps and Coded Action Apps have no `project.uiproj` / `project.json` — `uip solution project add` does not apply, and they are not packed by `uip solution pack`. They deploy independently via `uip codedapp publish` / `deploy`. A coded app directory can sit alongside a solution but is not part of its manifest. See [/uipath:uipath-coded-apps](/uipath:uipath-coded-apps).
 
+> **`.uis` bundles and the `pack` `.zip` are plain zip archives — unzip to inspect bundled contents.**
+
 ---
 
 ## Solution Lifecycle
@@ -73,6 +75,7 @@ uip solution
   │                                        (pre-rename CLIs expose this as `new`; see SKILL.md "CLI Surface Probe")
   ├── delete <solution-id>                Delete a solution from Studio Web
   ├── upload <path>                       Upload solution to Studio Web
+  ├── restore <solution>                  Resolve NuGet deps in place before pack (needs login; no package produced)
   ├── pack <solution> <output>            Pack into a deployable .zip package
   ├── publish <package>                   Upload packed solution to UiPath
   ├── project

package/skills/uipath-test/SKILL.md

@@ -147,7 +147,8 @@ Common `uip tm` commands organized by resource type.
 
 | Command | Purpose |
 |---|---|
-| `uip tm attachment download --execution-id <EXECUTION_ID>` | Download attachments for test cases in an execution. Optional `--project-key`, `--test-set-key`, `--test-case-name`, `--only-failed`, `--result-path <DIR>`. |
+| `uip tm attachment download --execution-id <EXECUTION_ID>` | Download attachments for test cases in an execution. |
+| `uip tm attachment upload --object-id <UUID> --object-type <type> --file <path>` | Upload a file as an attachment to a Test Manager object (e.g. `--object-type testCaseLog`). |
 
 ### Result Commands
 

package/skills/uipath-troubleshoot/SKILL.md

@@ -6,16 +6,16 @@ when_to_use: "User asks why something failed, broke, stopped, hung, was stuck, r
 
 # UiPath Troubleshooting Agent
 
-You orchestrate a hypothesis-driven troubleshooting investigation. You manage the loop, delegate to sub-agents, and present findings to the user.
+Orchestrate a hypothesis-driven troubleshooting investigation: manage the phase loop, delegate to sub-agents, present findings.
 
-All agents (including you) follow the invariants and confidence-level behavior defined in `agents/shared.md`.
+All agents (including you) follow the invariants and confidence-level behavior defined in `agents/shared.md` (§ Invariants, § Confidence-Level Behavior).
 
 ## 1. Critical Rules
 
 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.
+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.
 
@@ -31,6 +31,7 @@ All state lives in `.local/investigations/` (relative to working directory). Sch
 | `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 |
 
 Sub-agents write raw responses to `raw/` immediately and don't keep them in context. You read evidence summaries, not raw files.
 
@@ -45,7 +46,7 @@ Update `state.json.phase` at each transition:
 | `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 `needs_input` |
+| `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 | — |
 
@@ -53,15 +54,12 @@ Update `state.json.phase` at each transition:
 
 ### TRIAGE
 
-Spawn triage sub-agent (`agents/triage.md`). Pass the user's problem description **as-is** — do NOT pre-classify or constrain scope.
+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).
 
-**Triage sanity gate:** Read triage evidence and verify it relates to the user's reported problem. If it's about a different process/queue/entity: discard, inform the user, re-spawn or ask for clarification.
-
-**Scope check:** Spawn scope-checker (`agents/scope-checker.md`). If missing domains found, use `AskUserQuestion` to ask the user whether to expand. If approved, re-spawn triage with the missing domains. If unnecessary domains found, remove them from `state.json.scope.domain`.
-
-**User input:** If triage returned `needs_user_input: true`, present the question via `AskUserQuestion`. When the user responds, **continue the existing triage agent** via `SendMessage` (the agent result includes the agent ID) — do NOT spawn a fresh triage agent. A fresh spawn re-reads all instructions and re-discovers everything from scratch. Only re-spawn triage if the user's answer fundamentally changes scope (different product, different entity type).
-
-**Never skip the hypothesis loop.** Even if the triage evidence looks conclusive, always proceed through GENERATE → TEST → EVALUATE. Triage classifies and gathers data — it does not determine root causes. A "clear" error message may have a non-obvious underlying cause that only the hypothesis-test cycle would surface.
+**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.
 
 ### GENERATE HYPOTHESES
 
@@ -75,7 +73,7 @@ Test every hypothesis sequentially (highest confidence first). For each, spawn h
 
 **Validate:** Reject and re-spawn if `elimination_checks` are missing/incomplete. For medium/low, also reject if `execution_path_traced` has unverified downstream entities.
 
-**Reactive scope check:** If evidence references entities/errors from an out-of-scope domain, spawn scope-checker. Otherwise skip.
+**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.
 
 **Classify and act:**
 
@@ -86,7 +84,7 @@ Before classifying as **explains-WHY**, apply the upstream-cause gate. The mecha
 - **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 high-confidence eliminated** → re-invoke generator with `trigger: "scope_adjustment"` and eliminated IDs to produce from medium/low + docsai.
+- **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).
 
 **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.
 
@@ -94,8 +92,9 @@ Before classifying as **explains-WHY**, apply the upstream-cause gate. The mecha
 
 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 `## Causes` and
-`## Resolution` sections, and the evidence files, then writes
+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:
 
 - `verdict: "verified"` — the confirmed hypothesis names a specific cause
@@ -118,10 +117,7 @@ The verifier reads `hypotheses.json`, the playbook's `## Causes` and
     Surface the textual gaps in the presenter's output so the user
     sees them.
 
-**Symptom ≠ cause** (shared.md invariant #9). A symptom-level match (the
-right error string, the expected non-zero exit code) confirms the playbook
-*match*, not the *cause*. The depth-verifier enforces this gate — do not
-skip it.
+**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 FROM USER
 
@@ -148,14 +144,14 @@ The presenter:
 
 Present the presenter's output verbatim to the user. After presenting:
 
-**Execute Post-presentation actions FIRST.** If the presenter's output contains a `## Post-presentation actions` section, you MUST run every action in that section in order before offering any generic follow-up. For each action:
+**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 (raw selectors and other XML/HTML render poorly inside `AskUserQuestion` options or previews — always print as plain text first, separate from the question).
+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 question and options the action specifies. Ask the project path (or any other missing input the action declares) in the same `AskUserQuestion` call when needed.
-4. If the user accepts, execute the "On user accept" procedure exactly as written — this is the documented resolution path. Do not improvise an alternative. If the procedure references a sub-skill (e.g., `uia-improve-selector`), check for it and 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 action.
-6. If the action's `Status` is `blocked` (the presenter could not assemble it because evidence was missing), surface the block to the user as a follow-up instead of asking them to approve an incomplete fix — name the missing evidence field and the agent that should have populated it.
+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).
@@ -172,6 +168,8 @@ Only after all actions are complete (accepted, declined, or surfaced as blocked)
 
 **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/`.

package/skills/uipath-troubleshoot/agents/depth-verifier.md

@@ -1,40 +1,39 @@
 # Depth-Verifier Sub-Agent
 
-You verify that any confirmed root-cause hypothesis is *deep enough* to act
-on. You do NOT generate new hypotheses, run CLI commands, or rewrite
-findings. Your sole output is a gate signal the orchestrator uses to
-decide whether to present the resolution or re-spawn one more
-hypothesis-tester round.
+Gate confirmed root-cause hypotheses for depth. Output: a `verdict`
+(`verified` | `shallow`) + gap list the orchestrator uses to decide —
+present the resolution, or re-spawn one more hypothesis-tester round.
+Do NOT generate hypotheses, run CLI, or rewrite findings (see Invariants).
 
 ## Inputs you read
 - `.local/investigations/state.json` — for `matched_playbooks` and `scope`
 - `.local/investigations/hypotheses.json` — every hypothesis with
   `is_root_cause: true`
 - The matched playbook file referenced by
-  `state.json.matched_playbooks[*].path` — read its `## Causes` and
-  `## Resolution` sections
+  `state.json.matched_playbooks[*].path` — read its `## Context` cause
+  list ("What can cause it") and `## Resolution` section
 - `.local/investigations/evidence/*.json` — for cause-specific evidence
 
 ## The three depth checks (per confirmed hypothesis)
 
-1. **Specific cause named.** The hypothesis's `evidence_summary` (or its
-   narrative description) must name *one* bullet from the playbook's
-   `## Causes` enumeration verbatim or as a clear paraphrase. The cause
-   must be **specific** — picking "the connection is invalid" when the
-   playbook lists four distinct sub-causes is not specific enough.
-
-2. **Evidence pinned to the chosen cause.** The evidence files must
-   contain a datum that distinguishes the chosen cause from the others
-   in the same `## Causes` list. A datum that confirms the *symptom*
-   (e.g., "ping returned 404") is NOT enough — it fits multiple causes.
-   You must find evidence that singles out *this* cause, e.g., file
-   contents showing ownership, folder bindings, configuration flags,
+1. **Specific cause named.** The hypothesis's `evidence_summary` (or
+   description) names *one* item from the playbook's cause list ("What
+   can cause it", under `## Context`) verbatim or as a tight paraphrase —
+   specific, not a vague generalization (e.g. "the connection is invalid"
+   when the playbook lists four distinct sub-causes).
+
+2. **Evidence pinned to the cause.** Evidence files contain a datum that
+   distinguishes the chosen cause from its siblings in the same
+   cause list. Symptom-level data (e.g. "ping returned 404") fits
+   multiple causes — not enough. Require evidence that singles out *this*
+   cause: file contents, ownership, folder bindings, configuration flags,
    trace attributes.
 
-3. **Resolution alignment.** The hypothesis's `resolution` field must
-   match the playbook's `## Resolution` branch keyed on the named
-   cause. If the playbook offers multiple branches under "If X, then …",
-   the chosen branch must correspond to the cause named in check 1.
+3. **Resolution alignment.** The playbook's `## Resolution` must contain
+   a branch keyed on the named cause. If it offers multiple branches
+   under "If X, then …", confirm one corresponds to the cause named in
+   check 1. (The hypothesis's `resolution` field is written later by the
+   orchestrator — do not depend on it being populated here.)
 
 ## Causal precedence
 
@@ -82,7 +81,7 @@ Write `.local/investigations/depth-check.json`:
   "verdict": "verified",                                   // or "shallow"
   "hypothesis_id": "H1",
   "playbook_path": "<path from state.json.matched_playbooks>",
-  "named_cause": "<verbatim or quoted paraphrase from playbook ## Causes>",
+  "named_cause": "<verbatim or quoted paraphrase from the playbook's 'What can cause it' list>",
   "evidence_for_cause": [
     "<file path under .local/investigations/evidence/ or .local/investigations/raw/>"
   ],
@@ -158,7 +157,7 @@ paraphrased), emit two separate gap entries — one of each kind.
 
 ## When you may declare `verified` despite incomplete evidence
 
-If a playbook's `## Causes` enumeration is truly exhaustive but a
+If a playbook's cause list ("What can cause it") is truly exhaustive but a
 specific cause cannot be distinguished from the available data
 (genuine data gap, not laziness), declare `verdict: shallow` with
 `gaps: ["cannot disambiguate causes X vs Y from available evidence"]`.

package/skills/uipath-troubleshoot/agents/hypothesis-generator.md

@@ -2,7 +2,7 @@
 
 Produce ranked hypotheses based on investigation state and evidence.
 
-**Follow `agents/shared.md` first** — all invariants and confidence-level behavior apply.
+See `shared.md` § Invariants and § Confidence-Level Behavior first.
 
 ## Inputs
 
@@ -16,9 +16,13 @@ Write or update: `.local/investigations/hypotheses.json` — see `schemas/hypoth
 
 ## Steps
 
-1. **Read state + evidence.** Verify the evidence relates to the user's reported problem (correct process, queue, entity). If it doesn't, STOP — write `needs_input.json` (see shared.md) flagging the mismatch.
-2. **If re-invoked**: read existing hypotheses — don't regenerate eliminated ones. Check `generation_context` for trigger (deepening a symptom? scope adjustment?) and read `generation_context.eliminated_ids` to know which hypotheses to skip. When `trigger: deepening`, each new sub-hypothesis MUST name a distinct upstream cause for the parent's confirmed state — not a paraphrase of the parent with different wording. If you cannot name a distinct upstream cause, write `needs_input.json` instead of restating.
-3. **Read matched playbooks** from `state.json.matched_playbooks`. If empty, skip to step 4. Otherwise, generate hypotheses for **every** matched playbook in a **single round** (see Single-round coverage rule in `shared.md`). The number of hypotheses per playbook follows the confidence-level behavior table in `shared.md` ("Generator" column).
+1. **Read state + evidence + signals.** Read `state.json`, `evidence/triage-initial.json` (especially its `signals` array — the structured fact inventory triage produced), and the matched + eliminated playbook lists. Verify the evidence relates to the user's reported problem (correct process, queue, entity). If it doesn't, STOP — write `needs_input.json` (see shared.md) flagging the mismatch.
+2. **If re-invoked:** read existing hypotheses; skip those in `generation_context.eliminated_ids` (never regenerate eliminated ones). On `trigger: deepening`, each new sub-hypothesis MUST name a *distinct upstream cause* for the parent's confirmed state — not a reworded paraphrase. If you cannot name a distinct upstream cause, write `needs_input.json` instead of restating.
+3. **Read matched playbooks** from `state.json.matched_playbooks` — these are pre-ranked by `signal_match_count` (highest specificity first). Honor that ordering: H1 is drafted from the top-ranked playbook, H2 from the second-ranked, etc. **Never draft hypotheses from playbooks in `eliminated_playbooks`** — those have been disproved by signals already.
+
+   Generate hypotheses for **every** matched playbook in a **single round** (see Single-round coverage rule in `shared.md`). The number of hypotheses per playbook follows the confidence-level behavior table in `shared.md` ("Generator" column).
+
+   **Cite signals.** Each hypothesis records `signals_supporting` — the names of signals from `evidence/triage-initial.json.signals` that drove this hypothesis. A hypothesis with zero supporting signals is a contract violation: every drafted hypothesis must trace back to at least one observed signal, otherwise it is unfounded speculation.
 4. **Search documentation** — run up to 5 `uip docsai ask` queries for additional context. If after playbooks + 5 queries you still lack context: generate from what you have. If you truly cannot generate any hypothesis, write `needs_input.json` (see shared.md).
 5. **Inspect for explicit fault signals first.** Before drafting any hypothesis, scan triage evidence for explicit fault data — exception stacks, error codes, faulted-state details, error-level logs, incidents, element/activity errorDetails. If any fault signal is present, the **originating-fault hypothesis** (what caused the fault to occur) MUST be drafted first and assigned the highest confidence. Persistence, propagation, cleanup, recovery-gap, or state-transition hypotheses go *after* it. Never lead the hypothesis set with a pattern that explains how a fault was handled or how its consequences propagated when an explicit fault stack is on hand.