@uipath/skills 1.195.0

package/skills/uipath-test/references/publish-and-link-guide.md

@@ -0,0 +1,111 @@
+# Publish and Link Automation to Test Manager
+
+End-to-end pipeline: take a UiPath project's coded `[TestCase]` (or any test entry point), get it on Orchestrator, and bind it to a Test Manager test case so it can be executed from Test Manager. Each step lives in a different `uip` subdomain — this guide stitches them together.
+
+## Pipeline
+
+```
+uip rpa pack            → .nupkg
+uip or packages upload  → package on Orchestrator feed
+uip or folders list -n <folder-name> --all  → folder UUID (the 'Key' value)
+uip tm testcases list-automations  → test entry point name (the --test-name value)
+uip tm testcases link-automation   → test case is bound
+uip tm testcases run  / testsets run  → run
+uip tm wait              → block until terminal
+```
+
+## Prerequisites
+
+- Logged in: `uip login status --output json`. If not, `uip login`.
+- CLI surface probed (see [/uipath:uipath-test § Critical Rules #2](../SKILL.md#critical-rules)). Commands below use the post-rename shape; on a pre-rename CLI, translate via the [Pre-rename fallbacks](../SKILL.md#pre-rename-fallbacks) table (`testcases` → `testcase`, `run` → `execute`, etc.) before each call.
+- Project builds clean: `uip rpa build "<PROJECT_DIR>" --output json` returns `Result: "Success"`.
+- Test case exists in Test Manager: `uip tm testcases list --project-key <PROJECT_KEY> --output json`. Capture the `ObjKey` (e.g. `DEMO:1`) — it is the `--test-case-key` value.
+
+## Step 1 — Pack
+
+```bash
+uip rpa pack "<PROJECT_DIR>" "<OUTPUT_DIR>" --output json
+```
+
+Both arguments are positional — there is no `--project-dir` / `--project-path` flag here. See [/uipath:uipath-rpa § publishing-guide.md](../../uipath-rpa/references/publishing-guide.md) for full pack flags. Capture `OutputPath` from the JSON output — that's the `.nupkg` to upload.
+
+## Step 2 — Upload to Orchestrator
+
+```bash
+uip or packages upload "<NUPKG_PATH>" --output json
+```
+
+Capture the returned `Id` (the package name) and `Version` from the JSON output. Both are needed downstream.
+
+## Step 3 — Find the Orchestrator folder
+
+`link-automation` requires `--folder-key <UUID>` (NOT `--folder-path`). Discover it:
+
+```bash
+uip or folders list -n <folder-name> --all --output json
+```
+
+Filter for the folder that owns the package. The `Key` field is the UUID.
+
+> Use `--type <folder type> ` option to include folders of type personal, solution or standard.
+
+## Step 4 — Find the test entry point name
+
+A single package can expose multiple test entry points (one per `[TestCase]` method or test workflow). `link-automation` needs the exact `--test-name`. Discover it:
+
+```bash
+uip tm testcases list-automations --project-key <PROJECT_KEY> --folder-key <FOLDER_UUID> --output json
+```
+
+Optional filter: `--package-name <PACKAGE_ID>` (case-insensitive substring) when many packages live in the same folder. Pick the row whose `PackageName` matches the `Id` from Step 2 and note its `TestName`.
+
+## Step 5 — Link the automation
+
+```bash
+uip tm testcases link-automation \
+  --project-key <PROJECT_KEY> \
+  --test-case-key <TEST_CASE_KEY> \
+  --folder-key <FOLDER_UUID> \
+  --package-name <PACKAGE_ID> \
+  --test-name <TEST_NAME> \
+  --output json
+```
+
+The output should show `Result: "Linked"`. `link-automation` is idempotent on the `(test-case-key, package-name, test-name)` triple — re-running with the same triple replaces the previous link.
+
+## Step 6 — Run
+
+Two run modes — pick one:
+
+**Single test case** — uses `--test-case-id <UUID>`, NOT `--test-case-key`. Get the UUID from `uip tm testcases list --output json` (`Id` field):
+
+```bash
+uip tm testcases run --project-key <PROJECT_KEY> --test-case-id <TEST_CASE_UUID> --execution-type automated --output json
+```
+
+**Whole test set** — uses `--test-set-key`:
+
+```bash
+uip tm testsets run --test-set-key <TEST_SET_KEY> --execution-type automated --output json
+```
+
+Capture the returned `ExecutionId`.
+
+## Step 7 — Wait for terminal status
+
+```bash
+uip tm wait --execution-id <EXECUTION_ID> --project-key <PROJECT_KEY> --timeout 900 --output json
+```
+
+`--timeout 0` means no timeout. The output `Status` is `Passed` / `Failed` / `Cancelled` when the call returns.
+
+For result download, attachment download, and report generation: see [/uipath:uipath-test SKILL.md § Result, Attachment, Report Commands](../SKILL.md).
+
+## Common pitfalls
+
+- **`--test-case-id` (UUID) vs `--test-case-key` (`PROJECT_KEY:NUMBER`) vs `--test-case-keys` (plural, comma-separated).** Use `--test-case-key` for `update`, `delete`, `link-automation`, `unlink-automation`, `list-testsets`. Use `--test-case-id` for `run`, `list-steps`, `list-result-history`. Use `--test-case-keys` (plural) for the bulk-association verbs `testcases add` / `testcases remove`. They are NOT interchangeable.
+- **Wrong folder identifier.** `link-automation` requires the UUID. A folder name or path passed in `--folder-key` fails silently with "folder not found" or links to the wrong folder.
+- **Re-uploading the same package version.** Orchestrator rejects duplicates. Bump `--package-version` (or `project.json` `projectVersion`) on every change.
+- **Linking before upload.** `link-automation` does not validate the package exists on Orchestrator at link time — it only validates at run time. A stale `--package-name` value silently links to nothing and the next run fails with `package not found`. Always discover via `list-automations` (Step 4) before linking.
+- **Trying `uip tm testcases link` (no suffix).** The command is `link-automation`. Same for `unlink-automation`. See [/uipath:uipath-test § Anti-patterns](../SKILL.md#anti-patterns).
+- **Using the old singular names (`testcase`, `testset`, `execution`).** They were renamed to plural. See [/uipath:uipath-test § Anti-patterns](../SKILL.md#anti-patterns).

package/skills/uipath-test/references/test-result-report-guide.md

@@ -0,0 +1,96 @@
+# Test Report Generation Guide
+
+Detailed instructions for generating persona-tailored test reports from UiPath Test Manager.
+
+## Prerequisites
+
+- Authenticated session
+- CLI surface probed (see [/uipath:uipath-test § Critical Rules #2](../SKILL.md#critical-rules)). Commands below use the post-rename shape; translate via the [Pre-rename fallbacks](../SKILL.md#pre-rename-fallbacks) table on a pre-rename CLI.
+- A Test Manager project key
+- A Test Manager test set key
+
+---
+
+## Workflow
+
+1. **Fetch test executions from the test set**
+   - Use options like `status`, `execution-type`, `execution-finished-interval` to filter results as needed
+
+2. **Determine the report persona**
+   - Ask the user: "Who is this report for?"
+   - Example personas: `QA Engineer`, `Release Manager`, or `Developer`
+
+3. **Determine the output directory**
+   - Ask the user: "Which folder should the report be saved in? (or use the current directory.)"
+   - If the user provides a path, use it as-is (absolute or relative).
+   - If the user presses Enter or provides no path, use `.` (current working directory).
+   - Verify the directory exists before writing. If it does not exist, ask the user whether to create it or choose a different path. Do not create directories silently.
+
+4. **Include common metrics in all reports**
+   - Status of each test execution
+   - Count of test case logs per execution with result: `none`, `passed`, `failed`, `restricted`
+   - List of frequently failing test cases
+
+5. **Add persona-specific content**
+   
+   **For QA Engineer reports:**
+   - List regressions (previously passing tests that now fail). Ask if further details are needed → follow [Analyse More](#analyse-more).
+   
+   **For Developer reports:**
+   - Include the failing assertion message for each test case log. Ask if further details are needed → follow [Analyse More](#analyse-more).
+   
+   **For Release Manager reports:**
+   - Provide an overall summary with go/no-go decision support (success rate, blocker count, risk assessment)
+
+   **Other:**
+   - Ask for persona and what purpose is this report for.
+  
+6. **Validate the report before saving**
+   - Check that all required sections for the persona (steps 4–5, 7) are present. Add any missing sections before writing the file.
+
+7. **Ask if further details are needed**
+   - Follow [Analyse More](#analyse-more).
+  
+8. **Save the report**
+   - Save the report with all the fetched data.
+
+
+### Output Format
+
+The default filename is `test-report-<PERSONA>-<YYYY-MM-DD>.md`, where `<PERSONA>` is `qa`, `dev`, or `release` (use `custom` for any other persona) and `<YYYY-MM-DD>` is today's date.
+
+Ask the user: 
+- "Where should the repory be saved? (default: current directory)"
+- "What should the report be named? (default: `<DEFAULT_FILENAME>`)"
+
+Write the report to `<OUTPUT_DIR>/<FILENAME>`. Create the directories if not present
+
+Examples:
+- `./test-report-release-2026-04-13.md` (current directory, release manager, default name)
+- `/home/user/reports/my-report.md` (absolute path, user-provided name)
+
+---
+
+## Analyse More
+
+When the user asks for further details, use this loop:
+
+1. **Explore** — run `uip tm <resource> --help` to confirm the right subcommand and its flags
+2. **Execute** — run the command using IDs from the previous response, always with `--output json`
+3. **Validate** — if `items` is empty or the command errors, diagnose before retrying (max 3 attempts)
+4. **Repeat** — if the user asks for deeper detail, identify the next command and repeat
+
+<!-- | User asks about | Command |
+|---|---|
+| Regression history for a test case | `uip tm testcases list-result-history --project-key <KEY> --test-case-id <ID>` |
+| Failing assertions for a test case log | `uip tm testcaselog list-assertions --project-key <KEY> --test-case-log-id <ID>` |
+| Attachments for an execution | `uip tm attachment download --execution-id <ID>` | -->
+
+Stop when: the user is satisfied, the response has no more data, or 3 retries have failed.
+
+---
+
+## Anti-patterns
+
+- **Do NOT generate a report without asking for the persona** — a release manager receiving raw test logs is noise; a tester receiving only a pass/fail count is missing the detail they need.
+- **Do NOT fabricate test results** — only report data returned by the API. If executions are empty, tell the user there are no results for the selected filters.

package/skills/uipath-troubleshoot/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: uipath-troubleshoot
+description: "UiPath troubleshooting, diagnostics, and root-cause investigations across any UiPath product, feature, runtime, or artifact. Investigates errors, failures, faults, exceptions, regressions, performance problems, unexpected behavior, and silent malfunctions — answers why something failed, broke, stopped, hung, slowed down, returned wrong results, lost access, or stopped working after a change. Walks the available evidence (logs, traces, incidents, status fields, configuration, history) to identify the originating fault and explain what changed."
+when_to_use: "User asks why something failed, broke, stopped, hung, was stuck, returns wrong results, or behaves unexpectedly in any UiPath system. Triggers: 'why did X fail', 'find the cause', 'find why', 'what changed', 'investigate', 'diagnose', 'debug this', 'triage', 'help me figure out', 'what's wrong', 'root cause', 'fix this error', 'inspect this trace / incident / log / job / instance', 'X worked yesterday but now …'. Also fires on raw error messages, exception stacks, error codes, job / queue IDs, or 'stuck / orphan / zombie' state descriptions."
+---
+
+# UiPath Troubleshooting Agent
+
+You orchestrate a hypothesis-driven troubleshooting investigation. You manage the loop, delegate to sub-agents, and present findings to the user.
+
+All agents (including you) follow the invariants and confidence-level behavior defined in `agents/shared.md`.
+
+## 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.
+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.
+
+## 2. Investigation State
+
+All state lives in `.local/investigations/` (relative to working directory). Schemas in `schemas/`.
+
+| File | Purpose | Writers |
+|------|---------|---------|
+| `state.json` | Scope, phase, matched playbooks | triage, orchestrator |
+| `hypotheses.json` | All hypotheses + status | generator, tester, orchestrator |
+| `evidence/*.json` | Interpreted summaries | triage, tester |
+| `raw/*.json` | Full raw CLI/API responses | triage, tester |
+| `scope-check.json` | Domain expansion verdict | scope-checker |
+| `depth-check.json` | Depth-gate verdict on confirmed root causes | depth-verifier |
+
+Sub-agents write raw responses to `raw/` immediately and don't keep them in context. You read evidence summaries, not raw files.
+
+## 3. Phase State Machine
+
+Update `state.json.phase` at each transition:
+
+| Phase | Entry condition | Next |
+|-------|----------------|------|
+| `triage` | User describes problem (or new data arrives) | `hypotheses` |
+| `hypotheses` | Triage complete, playbooks matched | `test` |
+| `test` | Hypotheses ready, testing next in confidence order | `evaluate` |
+| `evaluate` | Tester returns verdict | `deepen`, `test`, or `depth_check` |
+| `deepen` | Confirmed symptom needs sub-hypotheses | `hypotheses` (re-invoke generator) |
+| `depth_check` | Hypothesis confirmed as root cause | `resolution` (verified), `test` (one re-round), or `needs_input` |
+| `resolution` | Depth check verified, or all hypotheses exhausted | `complete` |
+| `complete` | Findings presented to user | — |
+
+## 4. Investigation Flow
+
+### TRIAGE
+
+Spawn triage sub-agent (`agents/triage.md`). Pass the user's problem description **as-is** — do NOT pre-classify or constrain scope.
+
+**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.
+
+### GENERATE HYPOTHESES
+
+Spawn hypothesis generator (`agents/hypothesis-generator.md`). Behavior varies by confidence level per the table in shared.md.
+
+### TEST HYPOTHESES
+
+Test every hypothesis sequentially (highest confidence first). For each, spawn hypothesis tester (`agents/hypothesis-tester.md`).
+
+### EVALUATE (after each test)
+
+**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.
+
+**Classify and act:**
+
+Before classifying as **explains-WHY**, apply the upstream-cause gate. The mechanism (explicit-event check + implicit-presupposition check) is owned by the depth-verifier — see [`agents/depth-verifier.md` § Causal precedence](agents/depth-verifier.md). Orchestrator decision rule: if the gate identifies any upstream condition that has a `pending` or `supported` sibling hypothesis answering it, classify the current hypothesis as **describes-WHAT** regardless of evidence strength.
+
+**Sibling-precedence backstop** (orchestrator-only — siblings are visible here, not to the depth-verifier): if the candidate root cause is a persistence, propagation, cleanup, or state-transition pattern AND any sibling hypothesis is `pending` AND that sibling questions whether the underlying state has its own originating fault, the sibling MUST be tested before the candidate can be classified as **explains-WHY**. Stopping at the first confirmed hypothesis is incorrect when that hypothesis is downstream.
+
+- **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.
+
+**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.
+
+### DEPTH CHECK (after a hypothesis is confirmed as root cause)
+
+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
+`.local/investigations/depth-check.json` with one of:
+
+- `verdict: "verified"` — the confirmed hypothesis names a specific cause
+  from the playbook, has cause-specific evidence (not just symptom-level),
+  and recommends the matching resolution branch. Proceed to **Resolution**.
+- `verdict: "shallow"` — one or more depth dimensions are missing.
+  Inspect `gaps`. Each gap is classified `kind: "factual"` or
+  `kind: "textual"` by the depth-verifier. Routing rule:
+  - **If ANY gap has `kind: "factual"`** — spawn ONE additional
+    hypothesis-tester round on the same hypothesis to gather the
+    missing evidence, then re-spawn the depth-verifier. Stop after one
+    re-round. After that, either declare medium-confidence and proceed
+    to Resolution with the gaps surfaced to the user, or — if the gap
+    is a genuine data limitation — write `needs_input.json` and stop.
+  - **If ALL gaps are `kind: "textual"`** — do NOT spawn the tester.
+    Re-running the tester cannot fix narrative-level issues (paraphrase
+    looseness, wrong resolution branch picked) since those are the
+    *generator's* output, not the tester's. Accept the confirmed
+    hypothesis at `confidence: medium` and proceed to Resolution.
+    Surface the textual gaps in the presenter's output so the user
+    sees them.
+
+**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.
+
+### NEW DATA FROM USER
+
+If the user provides new data at any point (error messages, job IDs, logs, screenshots), go back to TRIAGE. Re-spawn triage with the new data. Do NOT patch new data into an in-progress investigation.
+
+## 5. Evaluation Rules
+
+**Root cause vs. symptom:** A finding that explains WHY the failure occurs is a root cause. A finding that describes WHAT happened (but not why) is a symptom — deepen it.
+
+**When to stop testing:**
+- High-confidence root cause confirmed → DEPTH CHECK; if verified AND no other co-equal-confidence playbook is still pending (see Co-equal-roots guard above), skip remaining hypotheses and go to Resolution. If co-equal playbooks remain pending, continue testing them first.
+- Medium/low root cause confirmed → DEPTH CHECK; if verified, ask user if they want to continue
+- All hypotheses exhausted (eliminated or inconclusive) → go to Resolution with "no root cause" outcome (no depth check needed when there is nothing to gate)
+
+## 6. Resolution
+
+Spawn the presenter agent (`agents/presenter.md`) with the confirmed hypothesis IDs and **all domains from `state.json.scope.domain`**. Do NOT pre-filter domains based on your judgment of their relevance to the causal chain — the presenter classifies root cause vs. propagation domains and searches docsai for each. Excluding a domain prevents the presenter from finding error handling patterns it was designed to surface.
+
+The presenter:
+- Assembles fixes from playbook `## Resolution` sections across all domains in the causal chain
+- Searches docsai for error handling and propagation patterns for every propagation domain
+- Applies all presentation rules (entity names from raw data, display names, UI labels)
+- Gates every fix step against documented sources
+
+Present the presenter's output verbatim to the user. After presenting:
+
+**Execute Post-presentation actions FIRST.** If the presenter's output 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:
+
+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).
+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.
+
+Do NOT skip the Post-presentation actions block when:
+- The matched playbook was downgraded from `high` to `medium` by depth-check (the resolution procedure is preserved across confidence downgrades — see `agents/depth-verifier.md` on textual gaps).
+- The depth-verifier flagged a cause-name mismatch (textual gap). A reclassified cause does NOT invalidate the playbook's interactive resolution; both can be reported together.
+- The recovered/recommended data was produced in a recommendation-only or unproven mode (`InferredRecoveryInfo`, `RecoverySuccessful: false`). The action carries a warning string for exactly this case — present it and let the user decide.
+
+Only after all actions are complete (accepted, declined, or surfaced as blocked) proceed to the generic follow-up:
+
+**If root cause found** — offer to help implement any further changes or clean up `.local/investigations/`.
+
+**If no root cause found** — use `AskUserQuestion` to offer: provide more data (re-triage), or open a UiPath support ticket with the evidence gathered.
+
+## 7. Operational Details
+
+**Spawning:** Read agent files just-in-time — only `agents/shared.md` + the specific agent file when you're about to spawn. Include full instructions and context in the prompt.
+
+**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

@@ -0,0 +1,165 @@
+# 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.
+
+## 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
+- `.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,
+   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.
+
+## Causal precedence
+
+A root cause is an *originating fault*: an event that, had it not
+occurred, would mean the failure never happened. A hypothesis that
+instead describes a consequence, propagation pattern, or persistence
+of an upstream fault is not a root cause — even if every check above
+passes — because eliminating the consequence does not prevent the
+fault.
+
+Apply two precedence checks:
+
+1. **Explicit-event check.** List every event the hypothesis treats
+   as given (the inputs to its causal chain) and ask "why did that
+   occur?". If any input has a more upstream answer that the current
+   hypothesis does not address, this hypothesis is downstream.
+
+2. **Implicit-presupposition check.** A persistence or
+   state-transition narrative typically *presupposes* an upstream
+   condition without naming it as an event — e.g., "state X did not
+   transition" presupposes "the system needed to transition out of
+   X", which presupposes "the system entered X for a reason worth
+   investigating". Identify the presupposed upstream condition and
+   require a separate hypothesis answering "why is the system in
+   that condition?". If `hypotheses.json` does not contain such a
+   hypothesis (or contains one still `pending`), the current
+   hypothesis cannot be root cause.
+
+If either check finds a missing upstream, reject the verdict — emit
+`shallow` with a `gaps` entry of `kind: "textual"` and
+`check: "causal_precedence"` (a string identifier distinct from the
+numbered depth checks 1–3 above; the orchestrator routes on `kind`,
+not on `check`), detail
+`"hypothesis describes consequence/persistence; upstream of <X> not investigated"`.
+The orchestrator must test the upstream condition before any
+downstream hypothesis can be accepted as root cause.
+
+## Output
+
+Write `.local/investigations/depth-check.json`:
+
+```json
+{
+  "schema_version": "1.1",
+  "verdict": "verified",                                   // or "shallow"
+  "hypothesis_id": "H1",
+  "playbook_path": "<path from state.json.matched_playbooks>",
+  "named_cause": "<verbatim or quoted paraphrase from playbook ## Causes>",
+  "evidence_for_cause": [
+    "<file path under .local/investigations/evidence/ or .local/investigations/raw/>"
+  ],
+  "resolution_alignment": "matches",                       // or "mismatch", or "missing"
+  "gaps": [
+    {
+      "kind": "factual",                                   // or "textual"
+      "check": 2,                                          // 1, 2, or 3 (corresponds to the depth check)
+      "detail": "<one-line description of the gap>"
+    }
+  ]
+}
+```
+
+If multiple hypotheses are flagged `is_root_cause: true`, write one
+entry per hypothesis as an array under a top-level `"checks"` key
+instead.
+
+If `verdict` is `shallow`, list every missing dimension in `gaps`. The
+orchestrator routes by gap `kind` (see Gap classification below).
+
+## Gap classification
+
+Each gap MUST be classified as either `factual` or `textual` so the
+orchestrator can decide whether re-spawning the hypothesis-tester is
+worth the cost.
+
+- **`kind: "factual"`** — applies to **check 2 only** (Evidence pinned).
+  The evidence files do not contain a datum that singles out the named
+  cause from neighboring causes in the same playbook list. Re-running
+  the hypothesis-tester *can* fix this by gathering more CLI output,
+  reading additional project-source files, or inspecting trace span
+  attributes.
+
+- **`kind: "textual"`** — applies to **checks 1 and 3** (Specific cause
+  named, Resolution alignment). The cause is named imprecisely
+  (paraphrase too loose, wrong sub-cause picked from a list of similar
+  causes) or the resolution branch listed in the hypothesis is the
+  wrong one for the named cause. Re-running the hypothesis-tester will
+  NOT fix this — the cause/resolution narrative is the *generator's*
+  output, not the tester's. The orchestrator handles textual gaps by
+  accepting the hypothesis at reduced confidence and surfacing the gap
+  to the user via the presenter, rather than re-running tests.
+
+  **A textual gap on check 1 (cause naming) does NOT invalidate the
+  matched playbook's `## Resolution` procedure.** Cause label and
+  remediation path are separable. When the matched playbook's resolution
+  is interactive (e.g., "show the user the recovered selector and ask
+  whether to apply"), that procedure remains the authoritative resolution
+  even if the cause description has been refined or partially refuted.
+  Do NOT advise switching to another playbook's resolution just because
+  that other playbook better names the cause — the original playbook's
+  remediation must still run. Note the cause refinement in the gap
+  `detail` so the presenter can surface it alongside the unchanged
+  resolution. The only situation in which the resolution branch itself
+  should change is a check 3 gap (Resolution alignment) — flag that
+  separately.
+
+If a single check produces a gap that has both factual and textual
+character (e.g., evidence is missing AND the named cause is
+paraphrased), emit two separate gap entries — one of each kind.
+
+## Invariants
+
+- You do NOT alter `hypotheses.json` or `state.json`.
+- You do NOT call sub-agents.
+- You do NOT run uip commands.
+- You read playbooks from paths in `state.json.matched_playbooks` —
+  same rule as every other agent.
+- Apply the standard `shared.md` invariants. In particular, **symptom
+  ≠ cause**: a symptom-level match alone does not satisfy check 1
+  or check 2.
+
+## When you may declare `verified` despite incomplete evidence
+
+If a playbook's `## Causes` enumeration 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"]`.
+The orchestrator will route to `needs_input` rather than re-test.

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

@@ -0,0 +1,38 @@
+# Hypothesis Generator Sub-Agent
+
+Produce ranked hypotheses based on investigation state and evidence.
+
+**Follow `agents/shared.md` first** — all invariants and confidence-level behavior apply.
+
+## Inputs
+
+- `.local/investigations/state.json`
+- `.local/investigations/evidence/` — all evidence so far
+- `.local/investigations/hypotheses.json` — if re-invoked (deepening or scope adjustment)
+
+## Output
+
+Write or update: `.local/investigations/hypotheses.json` — see `schemas/hypotheses.schema.md`
+
+## 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).
+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.
+
+6. **Generate hypotheses**, each with:
+   - Description, scope level, confidence, reasoning
+   - **Source citation** — which reference doc, search result, or playbook informed it
+   - `to_confirm` and `to_eliminate` evidence requirements
+   - `to_eliminate` MUST include execution path verification for multi-step hypotheses
+   - **Evidence requirements must be grounded in triage data.** Only reference entity types that actually appear in triage evidence or are explicitly mentioned in the matched playbook's `## Context`.
+   - **Evidence requirements must be feasible.** Check `state.json` data gaps before writing steps. If a data source is unavailable, propose an alternative for the **same entity** (never substitute a different entity). If no alternative exists, set `needs_user_input: true` in the evidence requirement with a description of what the user must provide.
+
+## Boundaries
+
+- Do NOT run uip commands against the platform — that's the tester's job
+- Do NOT test hypotheses — generate them with evidence requirements
+- Do NOT present hypotheses to the user — write them to `hypotheses.json`
+- Do NOT read source code files or query live platform data — that's the tester's job. Use triage evidence, playbooks, and docsai results to generate hypotheses.