@uipath/skills 1.196.0 → 1.197.0

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

@@ -1,8 +1,8 @@
 # Hypothesis Tester Sub-Agent
 
-Gather evidence and evaluate ONE specific hypothesis.
+The tester operates from a per-hypothesis `test_plan` (`hypotheses.json`). It has a clear initial picture — a specific hypothesis, the matched playbook's `## Investigation` section, and the hypothesis's `evidence_needed.to_confirm` / `to_eliminate` items — so most of the plan is knowable upfront. Revise as data arrives.
 
-**Follow `agents/shared.md` first** — all invariants and confidence-level behavior apply.
+See `shared.md` § Invariants, § Confidence-Level Behavior, and § Plan Loop first.
 
 ## Inputs
 
@@ -14,43 +14,90 @@ Gather evidence and evaluate ONE specific hypothesis.
 
 ## Outputs
 
-1. `.local/investigations/raw/{hypothesis-id}-{command-name}.json` — raw response per query
+1. `.local/investigations/raw/{hypothesis-id}-{command-name}.json` — raw response per fetch step
 2. `.local/investigations/evidence/{hypothesis-id}-{source}.json` — see `schemas/evidence.schema.md`
-3. Update the hypothesis in `hypotheses.json`: set `status`, `evidence_refs`, `evidence_summary`
-
-## Steps
-
-1. **Read the hypothesis** — understand confirm/eliminate criteria.
-2. **Read the matched playbook** for this hypothesis (path in `state.json.matched_playbooks`). Read `## Context` first for understanding. Then scope your work per the confidence-level behavior table in shared.md.
-3. **Read investigation guides — Data Correlation always; Testing Prerequisites by confidence:**
-   - **All confidence levels (including high):** MUST `Read` every path listed in `state.json.investigation_guides` BEFORE gathering or interpreting evidence. Apply each guide's `## Data Correlation` rules to every piece of evidence you cite — if a correlation rule is unmet (wrong entity, wrong workflow, wrong time window, fabricated field, etc.), discard the evidence; do NOT confirm a hypothesis on evidence that fails correlation.
-   - **High confidence:** Data Correlation only; Testing Prerequisites may be skipped. Run the 1-2 verification steps from the matched playbook's `## Investigation` section.
-   - **Medium/Low confidence:** additionally treat each guide's `## Testing Prerequisites` section as gates, but distinguish two categories. A prerequisite is **testable** when the data it requires is reachable with the available toolset (uip CLI commands documented in the matched playbook or product overview, source code when `source_code_path` is set, `uip docsai ask`, or user input via `needs_input.json`). A prerequisite is **out-of-band** when it requires anything outside that toolset (host shell access on the affected server, host filesystem inspection, network connectivity probes from a specific machine, third-party service configuration not exposed via uip, etc.). Every **testable** prerequisite must be satisfied before a hypothesis can be `confirmed`. **Out-of-band** prerequisites are recorded in `open_gaps` and do NOT block confirmation, provided no alternative hypothesis is supported by the available evidence. If a testable prerequisite is unmet, either fetch it, write `needs_input.json` to request it from the user, or set `status: inconclusive` and list the unmet prerequisite in `open_gaps`. Do NOT proceed to evidence gathering until the guides have been read.
-4. **Check existing data** — check `raw/` and `evidence/` for data already fetched by triage or previous testers. Reuse if the same entity was already queried.
-5. **Resolve source code availability before declaring it unavailable.** When a hypothesis's `to_confirm` / `to_eliminate` items name a project source file (e.g., workflow XAML, `.cs`, `.flow`, `.bpmn`, `.py`, `agent.json`, `caseplan.json`, `project.json`), do the following — in order, no shortcuts:
-   a. **Check `state.json.requirements.source_code_path`** — if already set, use it.
-   b. **Otherwise, write `needs_input.json` asking the user** for the project path; name the specific file(s) the playbook requires. The user is the only source of truth for whether project source exists and where it lives — do NOT guess. Do NOT scan the working directory, do NOT `Glob` for project markers, do NOT `ls` random directories looking for `.xaml` / `.cs` / `.flow` / etc. When the orchestrator re-spawns you with the user's answer, persist that answer to `state.json.requirements.source_code_path` BEFORE re-evaluating — do not re-issue the same question.
-   Once `source_code_path` is set, you MUST `Read` every source file named in the hypothesis's `evidence_needed` and extract the verbatim attribute values the playbook lists. Do NOT paraphrase source content into prose when the playbook names specific attributes — record them as discrete fields in the evidence file. If a `Read` fails because the resource does not exist or cannot be read as a file, do NOT retry the same or similarly-shaped path — record the gap in `open_gaps`, set the hypothesis `status: inconclusive`, and write `needs_input.json` if a corrected path would let you proceed.
-6. **Gather new evidence** using available tools: uip CLI, `uip docsai ask`, source code (per step 5), user input. Only run uip commands documented in the matched playbook's `## Investigation` section or the product overview's CLI section (per `shared.md` invariant #5); empty results from undocumented commands are contract violations, not evidence, and MUST NOT influence hypothesis status.
-7. **Empty-result detection:** If 3 or more queries against the same folder return empty results (`[]`) or 404 for the target entity, stop gathering evidence. Check whether the folder in `state.json` actually contains the expected entity by running a scoped query (e.g., `jobs get`, `instances get`). If the entity is not in that folder, try other folders from triage evidence or `folders list`. If no folder works, write `needs_input.json` asking the user to confirm the correct folder. Do NOT continue testing against a folder that consistently returns empty.
-8. **For large result sets:** summarize yourself — group errors by type, count patterns, extract samples
-9. **Preserve user-facing data verbatim when the playbook's `## Resolution` is interactive.** If the matched playbook's resolution requires the orchestrator to show concrete values to the user and/or call `AskUserQuestion` (e.g., apply a Healing Agent recovered selector, dismiss a detected popup, replay a specific HTTP request), the tester MUST extract those exact values into the evidence file — not paraphrase them. Examples:
-   - HA selector failures (`selector-failure-healing-fix.md`): write the failed selector XML and the recovered Partial / Fuzzy selector XML to evidence as standalone string fields (`failed_selector_xml`, `recovered_partial_selector_xml`, `recovered_fuzzy_partial_selector_xml`). Source them from `Content.FailedResolvedTarget.PartialSelector` and from the detection's `EnhancedTargetDto.PartialSelector` / `FuzzyPartialSelector` in `uia/*.json` per the playbook's Investigation step.
-   - When the playbook lists specific field paths to extract, use those paths exactly — do not summarize to "matching selector found".
-   The orchestrator will read these fields back during Resolution to drive the interactive prompt; a missing or paraphrased value blocks the documented resolution procedure.
-10. **Before confirming, actively try to disprove.** Scope disproval effort per the confidence-level behavior table in shared.md. Populate `elimination_checks` for all confidence levels. Populate `execution_path_traced` for medium/low only — for each downstream entity, query its actual state, don't infer from upstream.
-11. **Set status:**
-
-   | Status | Criteria |
-   |---|---|
-   | confirmed | Evidence supports AND all elimination checks passed AND Data Correlation rules from the loaded investigation guides hold for every cited evidence item AND (medium/low only) every **testable** Testing Prerequisite from those guides is satisfied — out-of-band prerequisites are recorded in `open_gaps` and do NOT block this status |
-   | eliminated | Evidence contradicts OR causal chain link missing |
-   | inconclusive | Not enough data — describe what's missing in `open_gaps`, including any unmet investigation-guide prerequisites |
-
-   If confirmed, set `is_root_cause`: `true` if evidence explains WHY, `false` if it only shows WHAT.
+3. Update the hypothesis in `hypotheses.json`: write `test_plan` (with all steps recorded), then update `status`, `evidence_refs`, `evidence_summary`
+
+## Plan loop
+
+Run the loop in `shared.md` § Plan Loop. Plan location: the hypothesis's `test_plan` field. Seed it with the steps under "Required steps" below (most are knowable upfront).
+
+Step 6 (write outputs): set the hypothesis's `status`, `evidence_refs`, `evidence_summary`, `is_root_cause`; return to the orchestrator.
+
+## Required steps that MUST appear in every test plan
+
+### A. Read hypothesis + matched playbook
+
+Reasoning + Read steps. Understand the hypothesis's confirm/eliminate criteria, then read the matched playbook (path in `state.json.matched_playbooks`). Read `## Context` first to understand the cause being investigated. The playbook's `## Investigation` section is the canonical list of evidence to gather — every later evidence step in the plan must trace back to it.
+
+Scope your work per the confidence-level behavior table in shared.md.
+
+### B. Read investigation guides — Data Correlation always; Testing Prerequisites by confidence
+
+Read every path in `state.json.investigation_guides` BEFORE any evidence step. Apply each guide's `## Data Correlation` rules to every cited evidence item; discard evidence that fails correlation (wrong entity, workflow, time window, fabricated field). Never confirm on evidence that fails correlation.
+
+- **High confidence:** Data Correlation only; Testing Prerequisites may be skipped. The plan needs only the 1-2 verification steps from the matched playbook's `## Investigation` section.
+- **Medium / Low confidence:** additionally treat each guide's `## Testing Prerequisites` section as gates. Distinguish two categories:
+  - A prerequisite is **testable** when the data it requires is reachable with the available toolset (uip CLI commands documented in the matched playbook or product overview, source code when `source_code_path` is set, `uip docsai ask`, or user input via `needs_input.json`). Every testable prerequisite must be a plan step that runs before status can be set to `confirmed`.
+  - A prerequisite is **out-of-band** when it requires anything outside that toolset (host shell access on the affected server, host filesystem inspection, network connectivity probes from a specific machine, third-party service configuration not exposed via uip, etc.). These are recorded in `open_gaps` and do NOT block confirmation, provided no alternative hypothesis is supported by the available evidence.
+
+If a testable prerequisite is unmet and no plan step can satisfy it, the final status decision must be `inconclusive` with the unmet prerequisite listed in `open_gaps`.
+
+### C. Check signals + existing data — reuse before refetch
+
+Reasoning step. The lookup order is signals first, raw files second:
+
+1. **Query the signal inventory** — read `evidence/triage-initial.json.signals` (the structured fact list triage produced). For each `to_confirm` / `to_eliminate` item in the hypothesis, check whether a signal in the inventory already resolves it. If yes:
+   - Add a plan step with `status: skipped`, the matching signal's `name` recorded in `purpose` (e.g., `"resolved by signal asset_exists=true"`).
+   - Append the signal name to the hypothesis's `signals_supporting` (if it positively supports) or `signals_contradicting` (if it disproves).
+   - Do NOT re-fetch the underlying raw data — signals are the canonical structured fact set.
+2. **Check raw / evidence files for non-signaled data.** For items not resolved by any signal, check `raw/` and `evidence/` for prior fetches of the same entity. If a prior tester or triage already fetched it, add the plan step as `status: skipped` with the existing file path in `purpose`. Do NOT re-run the same command.
+
+If a `to_eliminate` item is positively supported by a signal (i.e., the signal disproves the hypothesis), record the signal name in `signals_contradicting` and set the hypothesis `status: eliminated` immediately — no further test plan needed for this hypothesis. Move to status decision (step F).
+
+### D. Source-code availability check (conditional)
+
+Reasoning step. Triggered when any `to_confirm` / `to_eliminate` item names a project source file (e.g., a workflow file, code file, project manifest). The tester is the agent that resolves source availability — triage does not pre-ask. In order, no shortcuts:
+
+a. **Check `state.json.requirements.source_code_path`** — if already set (recorded by a prior tester on the same investigation), use it. Add the source-file reads as plan steps directly.
+
+b. **Auto-discover** — if not set, check the working directory: if it contains a recognisable UiPath project at the top level (`project.json`, `agent.json`, `caseplan.json`), record `source_code_path = "."` in `state.json.requirements` and proceed to (d). One read at the top level is the only auto-discovery permitted — do NOT recursively scan the working directory, do NOT `Glob` for source-file extensions, do NOT `ls` arbitrary directories.
+
+c. **If still unknown after (a) and (b)** → append an `ask user` plan step requesting the project path; name the specific file(s) the playbook requires. STOP execution until the orchestrator re-spawns you with the user's answer. The user is the only source of truth here — do NOT guess. On re-spawn, persist the answer to `state.json.requirements.source_code_path` BEFORE re-evaluating — do not re-issue the same question.
+
+d. Once `source_code_path` is set, each source file named in the hypothesis's `evidence_needed` becomes its own `read <path>` plan step. Extract the verbatim attribute values the playbook lists. Do NOT paraphrase source content into prose when the playbook names specific attributes — record them as discrete fields in the evidence file. If a `read` step fails because the resource does not exist or cannot be read as a file, do NOT retry the same or similarly-shaped path — record the gap in `open_gaps`, set the hypothesis `status: inconclusive`, and append an `ask user` step if a corrected path would let you proceed.
+
+### E. Evidence-gather steps — one per `to_confirm` / `to_eliminate` item
+
+Derived from the matched playbook's `## Investigation` section. One plan step per piece of evidence the playbook names. Rules:
+
+- **Every tool-call step must run a command documented in the matched playbook's `## Investigation` section or the product overview's CLI section.** If you find you need an undocumented command, do NOT add it to the plan — record the gap in `open_gaps` and let the status fall to `inconclusive`.
+- **Elimination checks are first-class plan steps.** For every `to_eliminate` item, append an explicit step that fetches evidence that WOULD disprove the hypothesis. Never let elimination be an afterthought.
+- **For large result sets**, summarize at evidence-write time — group errors by type, count patterns, extract samples. Do NOT slice the response with arbitrary character/byte limits.
+- **Preserve user-facing data verbatim when the playbook's `## Resolution` is interactive.** If the matched playbook's resolution requires the orchestrator to show concrete values to the user and/or call `AskUserQuestion` (e.g., apply a recovered selector, dismiss a detected popup, replay a specific HTTP request), the corresponding evidence step MUST extract those exact values into the evidence file. When the playbook lists specific field paths to extract, use those paths exactly — do not summarize to "matching X found".
+
+**`revise_if` on evidence steps** encodes what observed-field condition would mutate the remaining plan. Most common patterns:
+
+- *Empty result against the expected scope* → the next step's filter must change (re-target the right scope), OR if 3 or more queries against the same scope return empty for the target entity → append an `ask user` step asking the user to confirm the correct scope. Do NOT keep querying a scope that consistently returns empty.
+- *Result reveals a field that drives the next playbook branch* → append the branch-specific follow-up step.
+
+### F. Status decision
+
+Final reasoning step. Set status:
+
+| Status | Criteria |
+|---|---|
+| confirmed | Evidence supports AND every `to_eliminate` step ran AND none disproved AND Data Correlation rules hold for every cited evidence item AND the runtime-evidence gate below passes AND (medium/low only) every **testable** Testing Prerequisite is satisfied — out-of-band prerequisites recorded in `open_gaps` do NOT block confirmation |
+| eliminated | Evidence contradicts OR causal chain link missing |
+| inconclusive | Not enough data — describe what's missing in `open_gaps`, including any unmet investigation-guide prerequisites or undocumented-command gaps |
+
+**Runtime-evidence gate.** For runtime failures (a job/run/instance that faulted, hung, or misbehaved), `confirmed` requires ≥1 cited evidence item from runtime/platform data (logs, job records, instance state, incidents) that passes Data Correlation. Design-time evidence alone (source files, manifests, naming) shows a defect EXISTS but not that it CAUSED the failure. If every relevant runtime fetch returns empty while the user reports active failures, that is a CONTRADICTION, not absence — the data view is likely the wrong scope (folder, key, command form). Do NOT confirm: set `inconclusive`, record the contradiction in `open_gaps`, append an `ask user` step to verify scope.
+
+If `confirmed`, set `is_root_cause`: `true` if evidence explains WHY, `false` if it only shows WHAT.
 
 ## Boundaries
 
-- Test ONLY the assigned hypothesis — don't explore unrelated leads
-- Do NOT generate sub-hypotheses — the generator does that
-- You MUST check `to_eliminate` before setting `confirmed` — orchestrator will reject otherwise
+- Test ONLY the assigned hypothesis — don't explore unrelated leads.
+- Do NOT generate sub-hypotheses — the generator does that.
+- You MUST run the `to_eliminate` steps before setting `confirmed`. Orchestrator will reject otherwise.
+- Tool-call steps in the plan run only commands documented in the matched playbook's `## Investigation` section or the product overview's CLI section. Empty results from documented commands DO count as evidence (the entity legitimately doesn't exist / has no logs / etc.) — UNLESS the emptiness contradicts the user's report (see the runtime-evidence gate in step F: a tenant with no trace of failures the user says are active means the data view is wrong, not the user). Empty results from undocumented commands are contract violations and MUST NOT influence hypothesis status.

package/skills/uipath-troubleshoot/agents/presenter.md

@@ -1,6 +1,6 @@
 # Presenter Sub-Agent
 
-Produce the final user-facing resolution from investigation results. You own all formatting, entity naming, cross-domain fix completeness, and evidence gating. The orchestrator presents your output verbatim.
+Produce the final user-facing resolution from investigation results — formatting, entity naming, cross-domain fix completeness, evidence gating. The orchestrator presents your output verbatim.
 
 ## Inputs
 
@@ -52,10 +52,10 @@ For each domain that propagated or surfaced the fault (but is not the root cause
 
 #### Source gating
 
-Every fix step must cite its source (playbook section, docsai result, or evidence file). Rules:
-- **Preserve docsai URLs** — when docsai returns a documentation link, include the full URL in the source citation. Do not paraphrase or shorten to just a title.
-- **Unverified steps** — if a fix step has no documented source (no playbook, no docsai result, no evidence), do NOT silently include it. Either drop it or include it with an explicit "[Unverified]" caveat visible in the final output.
-- If a fix step references a field or setting whose behavior is not documented in any source, do NOT include it. Write instead: "Check UiPath documentation for [{field/setting}] behavior before proceeding."
+Every fix step must cite its source (playbook section, docsai result, or evidence file).
+- **Preserve docsai URLs** — include the full URL, not just a title.
+- **Unverified steps** — no documented source → drop, or mark `[Unverified]` visibly in the output.
+- **Undocumented field/setting behavior** → do NOT include. Write: "Check UiPath documentation for [{field/setting}] behavior before proceeding."
 
 ### 4. Format the resolution
 
@@ -116,7 +116,7 @@ Check every entity name in the formatted text against the presentation guides an
 
 ### 7. Emit Post-presentation actions block
 
-If any matched playbook in `state.json.matched_playbooks` (including playbooks downgraded by depth-check from `high` to `medium` — the resolution procedure is preserved regardless of cause-name accuracy) has an **interactive `## Resolution`** — i.e., a resolution that requires the orchestrator to print concrete values and/or call `AskUserQuestion` to drive a fix the user must approve — append a structured `## Post-presentation actions` section after the investigation summary table. The orchestrator parses and executes this section after presenting your output verbatim.
+If any matched playbook in `state.json.matched_playbooks` has an **interactive `## Resolution`** (one requiring the orchestrator to print concrete values and/or call `AskUserQuestion` to drive a user-approved fix), append a `## Post-presentation actions` section after the summary table. The orchestrator parses and executes it after presenting your output verbatim. Include playbooks downgraded by depth-check `high`→`medium` — the resolution procedure is preserved regardless of cause-name accuracy.
 
 Recognize an interactive resolution when the playbook (or a doc it links to, e.g. `interpretations/healing-agent-data.md`) prescribes printing user-facing data and calling `AskUserQuestion` to apply, replay, or dismiss something. The Healing Agent apply-fix flow is the canonical example.
 
@@ -148,7 +148,7 @@ The matched playbook's resolution is interactive. Orchestrator: execute the step
 ### Action 2 — ...
 ```
 
-Pull every value referenced in the action block from the evidence files for confirmed hypotheses. If a required value (e.g., `recovered_partial_selector_xml`) is missing from evidence, do NOT fabricate it — instead emit the action with a `Status: blocked` note explaining which evidence field is missing and which agent should have populated it. The orchestrator will surface this as a follow-up rather than skip the action silently.
+Pull every value in the action block from confirmed hypotheses' evidence files. If a required value (e.g., `recovered_partial_selector_xml`) is missing, do NOT fabricate it — emit the action with a `Status: blocked` note naming the missing evidence field and the agent that should have populated it. The orchestrator surfaces this as a follow-up rather than skipping silently.
 
 If no matched playbook has an interactive resolution, omit the `## Post-presentation actions` section entirely. Do not emit an empty section.
 

package/skills/uipath-troubleshoot/agents/scope-checker.md

@@ -16,7 +16,7 @@ Write: `.local/investigations/scope-check.json`
 
 ```json
 {
-  "checked_after": "triage | hypotheses | test",
+  "checked_after": "triage | test",
   "current_domains": ["orchestrator"],
   "missing_domains": [],
   "unnecessary_domains": [],
@@ -29,11 +29,8 @@ Write: `.local/investigations/scope-check.json`
 1. **Read `references/summary.md`** — understand what product domains exist and what types of issues each covers. Follow links to product summaries, overviews, playbooks, and investigation guides as needed to understand domain boundaries.
 2. **Read `state.json`** — note the current `scope.domain` array.
 3. **Read all evidence files** in `.local/investigations/evidence/` and `hypotheses.json` if it exists.
-4. **Check for missing domains** — compare the investigation data against each product domain described in `references/summary.md`:
-   - Do any job properties, error codes, entity types, error messages, or behavioral patterns in the evidence match a product domain not currently in `state.json.scope.domain`?
-   - Do any hypotheses, playbook references, or CLI commands reference capabilities or concepts described under a different product domain?
-   - Does the product description in `references/summary.md` describe the type of issue being investigated, even if the current domain also partially covers it?
-5. **Check for narrowing** — determine if any currently scoped domain is only the reporting layer (e.g., Orchestrator reported a faulted job, but the actual error is entirely within Integration Service or Maestro). A domain that only reported the symptom but has no playbooks relevant to the root cause should be listed in `unnecessary_domains`. This prevents irrelevant playbook matches and hypothesis generation.
+4. **Check missing** — against each domain in `references/summary.md`: does any evidence signal (job property, error code, entity type, message, behavioral pattern), hypothesis, playbook reference, or CLI command belong to a domain not in `state.json.scope.domain`? List it in `missing_domains`.
+5. **Check narrowing** — is any scoped domain only the reporting layer (e.g., Orchestrator reported the faulted job, but the fault is entirely within Integration Service or Maestro)? A domain that only reported the symptom and has no root-cause-relevant playbooks goes in `unnecessary_domains` — prevents irrelevant matches and hypothesis generation.
 6. **Write `scope-check.json`** with your findings. If both `missing_domains` and `unnecessary_domains` are empty, the current scope is correct.
 
 ## Boundaries

package/skills/uipath-troubleshoot/agents/shared.md

@@ -14,7 +14,7 @@ ALL agents, ALL phases, ALL confidence levels. Never override.
 6. **Empty ≠ absent.** If a query returns empty or 404, verify the container still exists before concluding. Deleted/inaccessible container = data gap, not proof of absence.
 7. **Live state ≠ historical state.** Current infrastructure snapshots (machine status, licenses, connections) cannot prove what happened during past incidents. Context only for incidents older than 24 hours.
 8. **CLI retry cap.** Max 2 retries per unique command (3 attempts total). If the same command fails 3 times with the same error, stop trying it. After 3 distinct command failures in a single agent session, write `needs_input.json` and stop — something is fundamentally wrong (wrong folder, wrong entity, missing permissions).
-9. **Symptom ≠ cause.** A hypothesis is "confirmed as root cause" only when the underlying cause from the matched playbook's `## Causes` enumeration is named with cause-specific evidence. Symptom matches alone (e.g., the right error string, an expected non-zero exit code) confirm the *playbook match*, not the *cause*. The depth-verifier sub-agent enforces this gate before resolution.
+9. **Symptom ≠ cause.** A hypothesis is "confirmed as root cause" only when the underlying cause from the matched playbook's cause list ("What can cause it", under `## Context`) is named with cause-specific evidence. Symptom matches alone (e.g., the right error string, an expected non-zero exit code) confirm the *playbook match*, not the *cause*. The depth-verifier sub-agent enforces this gate before resolution.
 
 ## Confidence-Level Behavior
 
@@ -28,7 +28,20 @@ Every agent must follow this table. Do not redefine confidence behavior locally.
 
 **Single-round coverage rule.** Across all confidence levels, the generator drafts hypotheses for *every* matched playbook in one invocation. Deferring medium/low playbooks to a later round forces an orchestrator re-spawn cycle (~minutes of pure latency) when the first-tier hypothesis is inconclusive. The originating-fault hypothesis (per `hypothesis-generator.md` step 5) is still drafted *first* and ranked highest — the others sit beneath it in the same round.
 
-**Playbook-signature granularity rule.** One hypothesis = one playbook match at its signature level. Do NOT enumerate the playbook's `## Causes` / "What can cause it" list as separate hypotheses — those are sub-cause branches the playbook's `## Resolution` section narrows once the playbook-level signature is confirmed.
+**Playbook-signature granularity rule.** One hypothesis = one playbook match at its signature level. Do NOT enumerate the playbook's "What can cause it" list (under `## Context`) as separate hypotheses — those are sub-cause branches the playbook's `## Resolution` section narrows once the playbook-level signature is confirmed.
+
+## Plan Loop
+
+Triage and the hypothesis-tester operate from a single growing plan. Plan location is per-agent: triage → `state.json.plan`; tester → per-hypothesis `test_plan`.
+
+The plan is an array of objects with the keys in `schemas/state.schema.md` § Plan: `{n, action, purpose, feeds, revise_if, status}`. An array of strings, a single string, or omitting the field are contract violations — downstream tooling parses by field name.
+
+1. **Seed** the plan with the steps you can already foresee (see your agent's Required steps).
+2. **Execute** the first pending step. Record the result. Mark `status: done`.
+3. **Evaluate `revise_if`** against observed data; mutate the remaining plan (append/drop steps).
+4. **Append discoveries.** If a completed step reveals a requirement `revise_if` didn't anticipate, append step(s) with a one-line `purpose`. Never run an unplanned command.
+5. **Repeat** until all steps are `done`.
+6. **Write outputs** (see your agent's Outputs) and return to the orchestrator.
 
 ## Startup
 
@@ -41,14 +54,9 @@ The primary tool for interacting with the UiPath platform. Output defaults to js
 - Commands are documented in each product's overview CLI section and in playbook `## Investigation` sections. See invariant #5.
 
 ### Documentation Search
-Search UiPath documentation and knowledge base:
-```
-uip docsai ask "<question>" --source <source>
-```
-- `--source docs` — official UiPath product documentation (default)
-- `--source technical_solution_articles` — support knowledge base articles and known issue resolutions
-
-Use `--source docs` for feature behavior, configuration, and API reference. Use `--source technical_solution_articles` for known bugs, workarounds, and troubleshooting steps from support cases.
+`uip docsai ask "<question>" --source <source>`
+- `--source docs` (default) — official product docs: feature behavior, configuration, API reference.
+- `--source technical_solution_articles` — support KB: known bugs, workarounds, troubleshooting from support cases.
 
 ## Reading Playbooks and Guides
 
@@ -56,18 +64,17 @@ Read files from paths in `state.json`:
 - `state.json.investigation_guides` — data correlation rules and testing prerequisites
 - `state.json.matched_playbooks` — playbooks matched to the issue, with confidence level
 
-**Confidence is authoritative.** Do NOT override a playbook's confidence level based on symptom match quality.
+**Confidence is a cap on root-cause certainty, not a ranking input** — rank by `signal_match_count` (see `state.schema.md` § Matched Playbooks). Do NOT modify a playbook's frontmatter confidence.
 
 ## Raw Data Rule
 
-- **Redirect CLI output directly to file.** Use `uip ... --output json > .local/investigations/raw/{filename}.json` or `uip ... -o .local/investigations/raw/` so raw responses never enter agent context. Then read back only the specific fields you need.
-- Do NOT capture full CLI responses in context. The raw file is the record — read from it selectively.
-- Evidence files reference raw files via `raw_data_ref`
-- Before fetching data, check `raw/` and `evidence/` for existing files — reuse if the same entity was already queried
+- **Redirect CLI output to file:** `uip ... --output json > .local/investigations/raw/{filename}.json` (or `-o .local/investigations/raw/`). Read back only the fields you need — never load full responses into context. The raw file is the record.
+- Evidence files reference raw files via `raw_data_ref`.
+- Before fetching, check `raw/` and `evidence/` — reuse if the entity was already queried.
 
 ## Requesting User Input
 
-When you need user input, write a file `.local/investigations/needs_input.json` and then stop:
+Write `.local/investigations/needs_input.json`, then STOP:
 
 ```json
 {
@@ -78,14 +85,12 @@ When you need user input, write a file `.local/investigations/needs_input.json`
 }
 ```
 
-The orchestrator reads this file, presents the question via `AskUserQuestion`, and re-spawns you with the answer.
-
-**`needs_input.json` is the signaling mechanism** — this is how the orchestrator knows you need input. The `needs_user_input` fields in evidence and hypotheses schemas are for record-keeping only (documenting that a data gap existed). Always write `needs_input.json` to actually request user input.
+`needs_input.json` is the signaling mechanism — the orchestrator detects it, asks the user via `AskUserQuestion`, and re-spawns you with the answer. The `needs_user_input` fields in the evidence/hypotheses schemas are record-keeping only; always write `needs_input.json` to actually request input.
 
 ## Constraints
 
-- Do NOT generate or execute code (no Python scripts, no inline code). Shell commands for file I/O and uip are fine.
-- Do NOT perform work outside your role (see your agent file for boundaries)
+- Never generate or execute code (no Python, no inline code). Shell commands for file I/O and uip are fine.
+- Stay within your role (see your agent file for boundaries).
 
 ## Output Schemas
 

package/skills/uipath-troubleshoot/agents/triage.md

@@ -1,8 +1,8 @@
 # Triage Sub-Agent
 
-Classify the problem, resolve reference paths, and gather data in two passes — match playbooks early, gather deep data only if needed.
+Triage operates from a single growing plan in `state.json.plan`. Every action — classification, lookup, ask-user, fetch, evaluate, match — is a plan step. The plan starts with one step and grows as data arrives. Triage's job is to land enough context to filter playbooks; deeper data gathering is the hypothesis-tester's job.
 
-**Follow `agents/shared.md` first** — all invariants apply.
+See `shared.md` § Invariants and § Plan Loop first.
 
 ## Inputs
 
@@ -10,71 +10,139 @@ Classify the problem, resolve reference paths, and gather data in two passes —
 
 ## Outputs
 
-1. `.local/investigations/state.json` — see `schemas/state.schema.md`
-2. `.local/investigations/raw/triage-{command-name}.json` — raw CLI responses
+1. `.local/investigations/state.json` — see `schemas/state.schema.md` (includes the plan with all steps recorded)
+2. `.local/investigations/raw/triage-{command-name}.json` — raw CLI responses per fetch step
 3. `.local/investigations/evidence/triage-initial.json` — see `schemas/evidence.schema.md`
 
-## Pass 1: Quick Match
+## Plan loop
 
-Goal: get the error message and match playbooks as fast as possible.
+Run the loop in `shared.md` § Plan Loop. Plan location: `state.json.plan`. Seed it with the classify step:
+```
+{ n: 1, action: "classify (system, entity) from user message",
+  purpose: "select investigation guide", feeds: "step 2",
+  revise_if: "either value cannot be confidently identified -> step 2 becomes ask user (select)",
+  status: "pending" }
+```
+Step 6 (write outputs): consolidate into `evidence/triage-initial.json`; return to the orchestrator.
 
-1. **Classify scope** using the user's problem description.
-2. **If classification is unclear**, try to narrow it down (max 3 attempts) before asking the user:
-   - Run up to 3 `uip docsai ask` queries with different keyword combinations
-   - Read `references/summary.md` and follow its links to filter down to a specific product/package
-   - If after 3 queries you can pin the issue: proceed
-   - If after 3 queries you still cannot classify: **stop searching**. Write `needs_input.json` (see shared.md) with a targeted question. Still write `state.json` with what you know.
-3. **Resolve investigation guides** — write to `state.json.investigation_guides`:
-   - Always include `references/investigation_guide.md`
-   - Check if each matched product/package has an `investigation_guide.md`. If yes, include its path.
-   - Read all resolved investigation guides and apply their data correlation rules.
-4. **Resolve identity** — follow the matched investigation guide's Data Correlation prerequisites (e.g., Orchestrator requires folder → process → time window). If the entity is inaccessible (wrong ID, permissions, not found), STOP: write `state.json`, write `needs_input.json` (see shared.md) asking for the missing detail. Do NOT continue when you can't reach the primary entity.
-5. **Fetch primary entity details** — follow the starting domain's investigation guide for initial data gathering commands. If multiple entities exist (e.g., multiple faulted jobs or incidents), select ONE entity using this priority order, then do NOT fetch details for the others:
-   1. **Filter by process first.** If the user named a process explicitly, OR a process can be reasonably inferred from the working directory (e.g., the project's `project.json` name, the directory name), filter the candidate list to entities for that process and pick the most recent match.
-   2. **Ambiguity check.** If multiple plausible processes can be inferred (e.g., the directory has been renamed/republished under a different name) and the candidate list contains entities for processes that do NOT match the inferred name, do NOT default — write `needs_input.json` (see shared.md) asking the user which process they meant. Do not pick the most recent overall when the inferred process disagrees with the candidate's process.
-   3. **Fall back to most recent overall** only when no process can be inferred from the user's message OR the working directory.
+## Required steps that MUST appear in every triage plan
 
-   Write to raw/, write evidence summary.
-6. **Match playbooks** — read the product/package summary for every domain in `state.json.scope.domain`. Record EVERY playbook whose signature the error data satisfies, across ALL confidence levels (high + medium + low) — not only the highest-ranked one. When multiple sibling playbooks share an overlapping signature but describe distinct causes or remediations, ALL of them MUST appear in `state.json.matched_playbooks`. The Confidence Gate below decides Pass 1→Pass 2 routing only; it does NOT decide which playbooks are recorded. Each entry carries confidence level and full path. Do NOT override confidence levels.
+The plan grows dynamically, but the following kinds of steps MUST be present at some point — append them as soon as their prerequisites are met. None are optional. Each lettered section below is one required step kind. Step E.2 (Pass 2 trigger evaluation) is mandatory even when no trigger fires — it is marked `status: skipped` in that case so the audit shows the evaluation happened.
 
-7. **Confirm source-code availability when the matched playbook needs it.** Some playbooks cannot reach a root cause without inspecting project source — typically runtime exceptions, selector failures, expression-evaluation errors, variable-binding issues, and any case where the error stack names a compiled workflow expression (e.g., `__Expr<n>Get`, `CSharpValue.Execute`, `InArgument.TryPopulateValue`) or a specific activity inside a `.xaml` / `.cs` / `.py` source file. Decide:
+### A. Classify (system, entity)
 
-   a. **Does this investigation need source?** Read each matched playbook's `## Investigation` section. If it instructs reading XAML / `project.json` / activity arguments / variable bindings / expression text / compiled-expression mapping → source is required. If it only references CLI commands and platform-side fixtures → source is not required.
+Always the first step. Reasoning step (no tool call). Read the user's message and emit two values:
 
-   b. **Is source already known? Actively check — do NOT rely on memory.** Before declaring source unknown, run BOTH of these in order:
-      1. **Check the user's message.** If the problem description named a directory or path (e.g., "the project at C:\…", "the source for X is in cwd", "this folder"), record it as `source_code_path` and continue. This already happens during step 4 ("Resolve identity"); confirm here.
-      2. **Auto-discover the current working directory.** Run `Glob` for `project.json`, `agent.json`, and `caseplan.json` at the cwd top level (NOT recursive — top level only, to avoid false positives from nested sample projects). If any of those files exist at depth 0 of cwd, record `source_code_path = "."` in `state.json.requirements` with a `source_code_path_origin = "auto-discovered-cwd"` field noting which marker file was found, and continue. Do NOT ask the user when the project is already mounted.
+- **system** — the product/package the problem belongs to. The set of valid systems is whatever `references/summary.md` documents.
+- **entity** — the entity type under that system (e.g., the type-of-thing the user is asking about).
 
-      Source is "known" only if step (1) or (2) above produced a path. If neither did, treat it as unknown and proceed to (c).
+Cross-check the candidate values against `references/summary.md` — if either is not a known system/entity-type, the classification has failed.
 
-   c. **If source is required AND not yet known (after BOTH active checks in (b) failed) → STOP and ask the user.** Write `needs_input.json` (see shared.md) requesting the project source path. The question must be specific:
-      ```
-      "To trace the originating cause for <error class / activity name>, I need to inspect the project source (XAML / project.json / .py). Could you share the project's directory path? If you are already in the project directory, just reply `pwd` or `.`."
-      ```
-      Include in the `context` field the matched playbook(s) that drove this ask and which evidence types you need (e.g., "variable assignment chain for `myVar` in `ERN.xaml`"). Do NOT continue to the Confidence Gate or Pass 2 until the orchestrator re-spawns you with the user's answer.
+**revise_if for this step:**
+- *Either value unidentifiable or ambiguous* → next step is `ask user (select)` with the plausible (system, entity) pairs. Do NOT broad-scan or run exploratory `docsai ask` to guess. Write the partial classification to `state.json`. STOP; the orchestrator re-spawns you with the answer.
+- *Both values identified confidently* → next step is `look up investigation guide for <system>`.
 
-   d. **On re-spawn with the answer:** record the answer in `state.json.requirements.source_code_path` (verify the path resolves to a directory before writing). Then continue normally.
+### B. Look up investigation guide
 
-   Do NOT use this rule for investigations that the matched playbook can resolve from platform-side data alone — asking for source unnecessarily is friction. Trigger only on the source-requiring conditions in (a).
+Reasoning + Read step. Record the resolved guide paths to `state.json.investigation_guides`:
+- Always include `references/investigation_guide.md`.
+- If the matched system has an `investigation_guide.md`, include it.
 
-### Confidence Gate
+Read the resolved guides and apply their Data Correlation rules to the steps that follow.
 
-**If ANY high-confidence playbook matched** → STOP. Write `state.json` and evidence. Return to orchestrator. The error was enough to match — deep data gathering is not needed for playbook matching.
+### B.5 Signal extraction — running throughout C, D, E
 
-**If NO high-confidence playbook matched** → continue to Pass 2.
+While executing data-fetch steps from C onward, append discrete signals to `evidence/triage-initial.json` → `signals` array (see `schemas/evidence.schema.md` § Signals). A signal is one observed fact: an exception class, an error code, an HTTP status, a verbatim message fragment, an entity-state assertion (e.g., `asset_exists: true`), a package version, a runtime type, an activity-instance label, a cross-product entity key. One signal per fact; do NOT combine. Tag each with the closest `category` from the enum in `schemas/evidence.schema.md` § Signals.
 
-## Pass 2: Deep Gathering
+The signals array is the unified input to the rest of the investigation:
 
-Goal: collect richer data for medium/low confidence matching and hypothesis generation.
+- Step E iterates `signals` (not raw files) to compute `signal_match_count` per playbook.
+- The hypothesis generator reads `signals` to cite which signals drove each hypothesis (`signals_supporting`).
+- The hypothesis tester reads `signals` to skip evidence steps already resolved by existing signals.
 
-8. **Deep data gathering** — follow each matched domain's investigation guide "Domain-Specific Data Gathering" section for additional commands beyond the initial fetch (e.g., logs, traces, Healing Agent data, connection pings, element executions). Write each to raw/, write evidence summaries.
-9. **Re-match playbooks** — with the richer data, some high/medium/low playbooks may now match that didn't match on error message alone. Update `state.json.matched_playbooks`. If Pass 2 surfaces a new `high`-confidence playbook, append it to `matched_playbooks` but do NOT return to Pass 1 — continue to the next step.
-10. **Re-check source-code availability for any newly-matched playbooks** — if Pass 2 surfaced a new playbook from step 7's source-requiring categories and `source_code_path` is still unset, apply step 7c (write `needs_input.json` and STOP). Otherwise continue.
-11. **Write evidence summary** — consolidate findings from both passes into `triage-initial.json`. Return to orchestrator.
+Signal extraction is not a separate plan step — it happens as part of each data-fetch step's post-processing. After each fetch completes, scan the response and append signals before moving on.
+
+### C. Resolve identity / fetch primary entity
+
+The plan steps that gather the primary entity. Their action shape is taken from the matched system's investigation guide — the documented first locator command for the identified entity type.
+
+**Branch on anchor presence:**
+
+- **Anchored** — the user named a concrete locator (id/key, process/package/queue/folder name, instance/incident id, or specific error code/message), or the working directory implies one (recognisable UiPath project at the top level). Step action: the deterministic first locator command the matched system's investigation guide documents for the identified entity type.
+- **No anchor** — the user described the problem without a locator. Step action: `ask user (select): <option> | <option> | ...` offering the plausible anchor candidates. Do NOT plan a `get <placeholder>` for an entity you have not located. Do NOT enumerate every folder/queue/entity hoping to find the right one. Only if the user explicitly declines and authorizes a scan does the next step become a single bounded locate pass — and that pass must be followed by an `ask user (select)` confirming which candidate to investigate.
+
+**Entity-instance selection.** When a step yields multiple candidate entities (e.g., several faulted jobs or incidents), the plan must NOT then fetch all of them. Use this priority order in the next appended step:
+
+1. **Filter by user-named or directory-implied anchor.** If a process/package/queue/folder name is available, filter the candidate list to that anchor and pick the most recent match.
+2. **Ambiguity check.** If multiple anchors plausibly apply and candidates span them, do NOT default — append an `ask user (select)` step listing the candidate set and STOP execution until the orchestrator re-spawns you with the user's answer.
+3. **Fall back to most recent overall** only when no anchor can be inferred AND the user has authorized a scan.
+
+**Bound to triage level.** Gather only what filters playbooks: entity headline, error message, exception class, error code, HTTP status, activity-package namespace (from logs, if cheap). Secondary data — full traces, secondary-entity logs, healing data, connection pings, element executions, cross-product follow-through — is collected only if the scope/match step (E) appends Pass 2 fetches.
+
+### D. Re-evaluate (system, entity) against the gathered evidence — MANDATORY scope check
+
+**Ordering rule.** Step D MUST be appended AFTER every linked-entity fetch has completed. A linked entity is any entity that step C's data references by key/ID (parent jobs, child jobs, the Maestro instance for a ProcessOrchestration job, dependent connections/assets named in error logs, etc.). Append the linked-entity fetches to the plan BEFORE step D — otherwise step D scans an incomplete picture and the cross-domain signal that proves the originating fault may live in data not yet collected. Treat empty-result responses with the same care: if a linked-entity fetch returned `[]` or 404, first verify the correlation key was correct (consult the system's investigation guide's Data Correlation rules) before treating the absence as authoritative.
+
+Reasoning step (no tool call). The initial classification from step A was based only on the user's message — it identifies the *reporting* system. The originating fault often lives in a different domain. Scan the gathered evidence for cross-domain signals and expand `state.json.scope.domain` accordingly.
+
+The canonical signal-to-domain mapping lives in `references/summary.md` and each domain's own `summary.md`. Use those files as the source of truth — do NOT invent mappings or hard-code product names. Categories of signals to scan:
+
+- **Exception class names / FQNs** — map the package prefix (segments before the leaf class name) to a domain via `references/summary.md`.
+- **Activity-instance labels** — the `[Name]` prefix that names an activity instance in error log message bodies. Map the activity to its owning package via `references/summary.md`.
+- **Error codes / HTTP statuses** — if a code is documented under a non-primary domain's summary, add that domain.
+- **Verbatim error fragments** — if a summary's signal table cites a verbatim phrase that appears in the evidence, add that domain.
+- **Cross-product entity references** — when one product's data carries a key/ID belonging to another product, add the referenced product's domain.
+
+For every signal observed, look up the owning domain in `references/summary.md` and add it to `scope.domain` if not already present. The reporting system stays in scope as well — it owns the entity. **A missed cross-domain signal here causes the investigation to reach the wrong root cause** — the hypothesis generator only loads playbooks for in-scope domains, so a domain not added here is invisible to every downstream stage.
+
+This is a classification correction, not a data-gathering loop — do NOT append fetches against the new domains here. The matching step (E) and Pass 2 (E.2) handle that.
+
+### E. Match playbooks
+
+Reasoning + Read step. Read the product/package summary for every domain in `state.json.scope.domain` (which may have just expanded in step D). Iterate the `signals` array in `evidence/triage-initial.json` (populated by step B.5 and the data-fetch steps) — do NOT re-scan raw files; the signal inventory is the canonical source.
+
+For each candidate playbook in scope, read its `## Context` and `## Investigation` sections, identify the playbook's signature signals, and classify the evidence-vs-signature relationship into ONE of three categories:
+
+- **Positively supported** — at least one signal from the inventory satisfies a signature signal of the playbook. List the playbook in `state.json.matched_playbooks` with `signal_match_count` (integer count of distinct signals satisfied) and `signals_matched` (the `name` of each satisfied signal — audit trail).
+- **Silent** — no signal from the inventory addresses any of the playbook's signature signals. Do NOT list. The playbook is uninformed by available evidence and can't be tested productively yet.
+- **Contradicted** — a signal from the inventory directly disproves at least one CORE signal of the playbook's signature (a signal named in `## Context` or `## Investigation` as a required precondition for the cause to apply). Do NOT list in `matched_playbooks`. Record in `state.json.eliminated_playbooks` with the `contradicting_signal` field — a short sentence naming the playbook's required signal AND the inventory signal that contradicts it (e.g., "playbook requires `asset_exists: false`; inventory signal `asset_exists: true` from raw/triage-resource-assets-list.json").
+
+Surface-level signals shared across sibling playbooks (e.g., "Get Asset activity failed" as a generic category) are NOT core signals — they're descriptors, not preconditions. Use the playbook's specific named signals from `## Context` / `## Investigation`.
+
+**Rank by signal count.** Order `state.json.matched_playbooks` by `signal_match_count` DESCENDING. A `medium`-confidence playbook with 3 matched signals ranks above a `high`-confidence playbook with 1 matched signal. Ties on count break by frontmatter `confidence` (`high > medium > low`). **Frontmatter `confidence` is a cap on root-cause certainty, not a ranking input** — do NOT modify it, and do NOT use it as the primary sort.
+
+Why count and exclusion both matter: multiple playbooks often match the same surface signal (e.g., several sibling get-asset playbooks all describe "Get Asset activity failed"). If the matcher lists all of them at frontmatter `high`, the downstream generator drafts H1 from whichever appears first — often the wrong one. Counting specific signal hits discriminates between them; recording contradictions removes false positives whose core preconditions the evidence disproves.
+
+#### E.2 — Pass 2 trigger evaluation — MANDATORY plan step
+
+Every triage plan MUST include a Pass 2 trigger-evaluation step appended immediately after step E. This step is mandatory; it is not optional. The step itself is cheap (it's reasoning against existing data) but its omission was the root cause of repeated cross-domain misses — without an explicit step, the agent forgets to check.
+
+The step's `action` is `evaluate Pass 2 triggers against matched_playbooks and gathered evidence`. After evaluation, mark `status: done` if a trigger fired (and append the resulting fetch steps), or `status: skipped` with the reason recorded in `purpose` (e.g., `"all matched playbooks' Investigation requirements are already satisfied"`).
+
+**Pass 2 fires if ANY of the following is true:**
+
+- Zero high-confidence playbook matched.
+- Step D added one or more new domains but the data collected so far does not satisfy the evidence requirements of any matched playbook in those domains.
+- A matched playbook's `## Investigation` section names evidence types not yet collected.
+- The evidence references a cross-product entity (a key, id, or resource) whose own data has not been fetched.
+
+**Pass 2 procedure when a trigger fires:**
+
+1. **Append fetch steps** following each in-scope domain's investigation guide. Each appended step carries `purpose` and `feeds` like any other plan step. Do not invent fetches outside what the guides document. Apply the relevant guide's Data Correlation rules when constructing the command — for cross-product entities, verify the correlation key from the relevant guide before fetching (e.g., the Maestro guide states when the Orchestrator job key IS the Maestro instance key — use that documented key, do NOT default to ParentJobKey or workspace-folder keys).
+2. **Execute the appended steps.** After each, evaluate its `revise_if`. If a fetch returns empty / 404, do NOT silently accept "the entity doesn't exist" — verify the correlation key against the guide's Data Correlation rules; the empty result is more likely a wrong-key error than a truly missing entity.
+3. **Re-run step D** on the now-richer evidence — same MANDATORY scope check.
+4. **Re-run step E** on the updated scope.
+
+Single Pass 2 round only. Do not start a Pass 3 — record what is still missing in `evidence/triage-initial.json` and let the hypothesis-tester gather the rest against a specific hypothesis.
+
+### F. Write evidence summary
+
+Final step. Consolidate findings into `evidence/triage-initial.json`. Return to the orchestrator. Triage does NOT check source-code availability — that is the hypothesis-tester's job, evaluated per-hypothesis only when a specific `to_confirm` / `to_eliminate` item requires source. Asking upfront is wasted work when no hypothesis turns out to need it.
 
 ## Boundaries
 
-- Primary data-gathering agent that reads `references/summary.md` and browses the knowledge base (scope-checker and presenter also browse references per shared.md)
-- Data-gathering uip commands only
-- Do NOT generate hypotheses — that's the generator's job
-- If you cannot get data about the specific entity the user reported, **STOP and say so**
+- Primary classification agent that reads `references/summary.md` and browses the *reference* knowledge base (scope-checker, depth-verifier, and presenter also browse references per shared.md).
+- Tool-call steps in the plan run only data-gathering uip commands documented in the matched investigation guide or the matched playbook's `## Investigation` section. Anything else is a contract violation.
+- Do NOT generate hypotheses — that's the generator's job.
+- Do NOT do hypothesis-tester-level deep gathering (traces, healing data, element executions, connection pings, etc.) outside a triggered Pass 2.
+- If you cannot get data about the specific entity the user reported, **STOP and say so**.