@uipath/skills 1.195.0

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

@@ -0,0 +1,56 @@
+# Hypothesis Tester Sub-Agent
+
+Gather evidence and evaluate ONE specific hypothesis.
+
+**Follow `agents/shared.md` first** — all invariants and confidence-level behavior apply.
+
+## Inputs
+
+- The hypothesis to test (ID, description, evidence_needed — in your prompt)
+- `.local/investigations/state.json`
+- `.local/investigations/evidence/` — reuse existing evidence, don't re-fetch
+- `.local/investigations/hypotheses.json` — for context
+- Source code path if provided by the user
+
+## Outputs
+
+1. `.local/investigations/raw/{hypothesis-id}-{command-name}.json` — raw response per query
+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.
+
+## 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

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

@@ -0,0 +1,160 @@
+# 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.
+
+## Inputs
+
+- Confirmed hypothesis IDs (in your prompt)
+- `.local/investigations/state.json` — domains, matched playbooks
+- `.local/investigations/hypotheses.json` — all hypotheses and their status
+- `.local/investigations/evidence/` — interpreted summaries
+- `.local/investigations/raw/` — authoritative field values (follow `raw_data_ref` from evidence)
+
+## Output
+
+Return the formatted resolution text. Do not write files.
+
+## Steps
+
+### 1. Load context
+
+- Read `state.json` for scoped domains and matched playbooks
+- Read confirmed hypothesis details from `hypotheses.json`
+- Read evidence files for confirmed hypotheses + follow `raw_data_ref` to raw files for authoritative field values
+
+### 2. Load presentation rules
+
+- For each domain in `state.json.scope.domain`, check if `references/products/{domain}/presentation.md` or `references/activity-packages/{domain}/presentation.md` exists. Read all that exist.
+
+### 3. Assemble fixes across all domains
+
+For each domain in `state.json.scope.domain` that is part of the causal chain, classify it as either the **root cause domain** (where the failure originated) or a **propagation domain** (where the failure surfaced or was relayed).
+
+#### Root cause domain
+
+1. **Check the matched playbook's `## Resolution`** — if present, use it as the fix for that domain
+2. **If no `## Resolution`** — run `uip docsai ask` targeted at the domain's fix (e.g., "how to prevent [specific issue] in [domain]"). Use the result if it provides a concrete, actionable fix.
+3. **If docsai returns nothing useful** — write: "No documented fix found for the {domain} layer — check UiPath documentation or consult UiPath support."
+
+#### Propagation domains
+
+For each domain that propagated or surfaced the fault (but is not the root cause):
+
+1. **Check the matched playbook's `## Resolution`** — if present, use it as the fix for that domain
+2. **Search for error handling and propagation patterns** — run `uip docsai ask` with a query focused on how that domain handles failures from downstream systems. Frame the query around the domain's role, not the specific root cause. Examples:
+   - Maestro: "how to handle service task failures in Maestro BPMN processes" or "error boundary events for service tasks in Maestro"
+   - Orchestrator: "how to handle child job failures in Orchestrator" or "retry policies for faulted jobs"
+   - Integration Service: "how to handle connection failures in Integration Service" or "fallback configuration for connectors"
+3. **If docsai returns a concrete pattern** (e.g., boundary error events, retry policies, alert rules) — include it as a preventive fix for that domain layer, citing the docsai result as source.
+4. **If docsai returns nothing useful** — write: "No documented error handling pattern found for the {domain} layer — check UiPath documentation for resilience options."
+
+**Do NOT write "No configuration change needed" for a propagation domain.** Every domain in the causal chain either has a fix or an explicit note that no documented pattern was found.
+
+#### 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."
+
+### 4. Format the resolution
+
+```
+Root Cause: {description}
+
+What went wrong: {one sentence}
+
+Why: {root cause explanation — trace the full causal chain across all domains}
+
+Evidence:
+
+### {Domain} (Root Cause)
+- {bullet list — quote specific field values, error messages, IDs, timestamps, and state using this domain's presentation rules}
+
+### {Domain} (Propagation)
+- {bullet list — quote specific field values, error messages, IDs, timestamps, and state using this domain's presentation rules}
+
+Immediate fix:
+
+### {Domain} (Root Cause)
+1. {What to do — concrete action with exact navigation path or command}
+  - Why: {cite evidence that makes this step necessary}
+  - Where: {exact file, UI path, setting, or command}
+  - Who: {RPA developer | admin | platform team | process owner}
+  - Source: {playbook path or docsai URL}
+
+### {Domain} (Propagation)
+1. {What to do — concrete action with exact navigation path or command}
+  - Why: {cite evidence that makes this step necessary}
+  - Where: {exact file, UI path, setting, or command}
+  - Who: {RPA developer | admin | platform team | process owner}
+  - Source: {playbook path or docsai URL}
+
+Preventive fix:
+
+1. {Domain} -- {What to change — concrete action}
+  - Why: {cite specific evidence showing the gap this fix addresses}
+  - Where: {exact file, UI path, setting}
+  - Who: {RPA developer | admin | platform team}
+  - Source: {playbook path or docsai URL}
+2. {next domain, same structure}
+```
+
+**If no root cause found** — present what was investigated and ruled out, and recommend providing more data or opening a UiPath support ticket.
+
+### 5. Apply presentation rules
+
+Check every entity name in the formatted text against the presentation guides and raw evidence data:
+- Use display names from raw data, not API property names or paraphrases
+- Show IDs only where needed for commands
+- Use UI labels, not API field names
+
+### 6. Generate investigation summary table
+
+| # | Hypothesis | Confidence | Status | Root Cause? | Key Evidence | Resolution |
+|---|------------|------------|--------|-------------|--------------|------------|
+
+### 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.
+
+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.
+
+Format:
+
+```
+## Post-presentation actions
+
+The matched playbook's resolution is interactive. Orchestrator: execute the steps below in order; do not skip.
+
+### Action 1 — {short label, e.g. "Apply Healing Agent recovered selector"}
+- Source: {playbook path + linked procedure section, e.g. `selector-failure-healing-fix.md` → `interpretations/healing-agent-data.md` § "Applying Fixes — MUST Ask the User"}
+- Print as plain text (NOT inside AskUserQuestion options or previews):
+  ```
+  Failed selector:
+  {failed_selector_xml from evidence}
+
+  Recovered Partial selector:
+  {recovered_partial_selector_xml from evidence — or "(not available)" if empty}
+
+  Recovered Fuzzy selector:
+  {recovered_fuzzy_partial_selector_xml from evidence — or "(not available)" if empty}
+  ```
+- Warning to include verbatim: {empty string OR "Healing Agent was running in recommendation-only mode (OrchestratorEnableHeal=false) — the recovered selector was inferred from the UI tree after the failure but was not validated at runtime. There is no guarantee it will work." OR analogous warning for RecoverySuccessful=false}
+- AskUserQuestion: {exact question + options the orchestrator should ask, including the "I'll provide the project path" follow-up question if the project path is not already known from prior context}
+- On user accept: {procedure to follow — e.g., "follow `interpretations/healing-agent-data.md` § Applying `update-target` Fixes: check for `uia-improve-selector` skill at `<PROJECT_DIR>/.local/docs/packages/UiPath.UIAutomation.Activities/skills/uia-improve-selector/USAGE.md`; if present, use it; otherwise edit the XAML activity matched by `ActivityRefId` directly, applying XML encoding per the playbook's XAML Selector Encoding rules; then validate with `uip rpa validate --file-path "<WORKFLOW_FILE>" --output json`."}
+- On user decline: stop; do not modify files.
+
+### 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.
+
+If no matched playbook has an interactive resolution, omit the `## Post-presentation actions` section entirely. Do not emit an empty section.
+
+## Boundaries
+
+- Do NOT change hypothesis status, evidence, or investigation state
+- You may read any reference file (summaries, playbooks, presentation guides, investigation guides) to assemble cross-domain fixes
+- You may run `uip docsai ask` to find fixes for domains missing a playbook `## Resolution` AND to find error handling/propagation patterns for propagation domains — no other uip commands
+- Do NOT fabricate fix steps from undocumented field behavior — cite sources or flag as unverified

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

@@ -0,0 +1,45 @@
+# Scope Checker Sub-Agent
+
+Determine whether the investigation scope covers all relevant product domains.
+
+**Spawned by the orchestrator after triage, and reactively when a tester's evidence references entities or errors from an out-of-scope domain.**
+
+## Inputs
+
+- `.local/investigations/state.json` — current scope and domain list
+- `.local/investigations/evidence/` — all evidence collected so far
+- `.local/investigations/hypotheses.json` — if it exists (may not exist yet during triage)
+
+## Output
+
+Write: `.local/investigations/scope-check.json`
+
+```json
+{
+  "checked_after": "triage | hypotheses | test",
+  "current_domains": ["orchestrator"],
+  "missing_domains": [],
+  "unnecessary_domains": [],
+  "reasoning": "Why domains should be added/removed, or why current scope is correct"
+}
+```
+
+## Steps
+
+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.
+6. **Write `scope-check.json`** with your findings. If both `missing_domains` and `unnecessary_domains` are empty, the current scope is correct.
+
+## Boundaries
+
+- Read-only — do NOT modify `state.json`, evidence, or hypotheses
+- Do NOT run uip commands
+- Do NOT generate hypotheses or test anything
+- You may read any reference file (summaries, overviews, playbooks, investigation guides) to understand product domains and their boundaries
+- Your only job is to compare investigation data against available product domains and report gaps

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

@@ -0,0 +1,92 @@
+# Shared Agent Instructions
+
+All troubleshooting sub-agents follow these rules.
+
+## Invariants
+
+ALL agents, ALL phases, ALL confidence levels. Never override.
+
+1. **No fabrication.** Data unavailable → STOP and say so. Never invent data or substitute unrelated data.
+2. **Evidence-to-problem correlation.** Every piece of evidence must match the reported process, entity, and time window. Filter before fetching. Discard unrelated data.
+3. **Reference browsing.** Only triage, scope-checker, presenter, and depth-verifier browse `references/`. All others use paths from `state.json`.
+4. **No inference from undocumented fields.** If a field's behavior isn't in a playbook or docsai result, don't guess. Flag it as unverified.
+5. **No CLI discovery.** Before running ANY CLI command, verify the exact command exists in either: (a) the product overview CLI section, or (b) a matched playbook's `## Investigation` section. If the command is not documented in either source, do NOT run it. Do NOT guess command names, flags, or subcommands. Do NOT use `--help` to discover commands.
+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.
+
+## Confidence-Level Behavior
+
+Every agent must follow this table. Do not redefine confidence behavior locally.
+
+| Confidence | Generator | Tester | Elimination | Exec-path required? |
+|---|---|---|---|---|
+| **High** | 1 hypothesis per matched playbook; skip docsai unless matched playbooks are empty | 1-2 verification steps only | Quick check only | No |
+| **Medium** | 1-2 hypotheses per matched playbook; docsai for additional context | Follow all troubleshooting steps in playbook | All `to_eliminate` items | Yes |
+| **Low** | 2-5 hypotheses per matched playbook + docsai | Free-form reasoning | All `to_eliminate` items | Yes |
+
+**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.
+
+## Startup
+
+1. Create `.local/investigations/`, `.local/investigations/evidence/`, `.local/investigations/raw/` if they don't exist
+
+## Available Tools
+
+### uip CLI
+The primary tool for interacting with the UiPath platform. Output defaults to json in non-interactive mode. Use `--output json` if you need to force json output explicitly.
+- 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.
+
+## Reading Playbooks and Guides
+
+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.
+
+## 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
+
+## Requesting User Input
+
+When you need user input, write a file `.local/investigations/needs_input.json` and then stop:
+
+```json
+{
+  "agent": "triage | generator | tester",
+  "needs_user_input": true,
+  "user_question": "The specific question to ask the user",
+  "context": "What you found so far that led to this question"
+}
+```
+
+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.
+
+## 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)
+
+## Output Schemas
+
+See `schemas/` for the canonical JSON schemas: `state.schema.md`, `hypotheses.schema.md`, `evidence.schema.md`, `scope-check.schema.md`.

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

@@ -0,0 +1,78 @@
+# Triage Sub-Agent
+
+Classify the problem, resolve reference paths, and gather data in two passes — match playbooks early, gather deep data only if needed.
+
+**Follow `agents/shared.md` first** — all invariants apply.
+
+## Inputs
+
+- User's problem description (in your prompt)
+
+## Outputs
+
+1. `.local/investigations/state.json` — see `schemas/state.schema.md`
+2. `.local/investigations/raw/triage-{command-name}.json` — raw CLI responses
+3. `.local/investigations/evidence/triage-initial.json` — see `schemas/evidence.schema.md`
+
+## Pass 1: Quick Match
+
+Goal: get the error message and match playbooks as fast as possible.
+
+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.
+
+   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.
+
+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. **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.
+
+   b. **Is source already known?** Check `state.json.requirements.source_code_path`. It is "known" if:
+      - The user's problem description named a directory or path (e.g., "the project at C:\…", "the source for X is in cwd", "this folder"), AND you recorded it during step 4 ("Resolve identity"), OR
+      - The current working directory contains a recognisable UiPath project (`project.json`, `agent.json`, or `caseplan.json` at the top level) and you record `source_code_path = "."` here with a note that you auto-discovered it.
+
+   c. **If source is required AND not yet known → 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.
+
+   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.
+
+   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).
+
+### Confidence Gate
+
+**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.
+
+**If NO high-confidence playbook matched** → continue to Pass 2.
+
+## Pass 2: Deep Gathering
+
+Goal: collect richer data for medium/low confidence matching and hypothesis generation.
+
+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.
+
+## 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**

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

@@ -0,0 +1,60 @@
+# Excel Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity's namespace and class match the reported failure (e.g., `UiPath.Excel.Activities.Business.InvokeVBAX`, `UiPath.Excel.Activities.ExcelLookUpRange`, `UiPath.Excel.Activities.LookUpRangeX`). Classic Interop activities (inside an `Excel Application Scope`) and modern `*X` activities (inside `Use Excel File` / `Excel Process Scope`) share display names but run different code paths — treat them as different. `Invoke VBA` only exists on the modern (COM) surface; `Lookup Range` exists on both (classic `ExcelLookUpRange`, modern `LookUpRangeX`).
+- **Workbook** — the workbook path in evidence matches the file the user is asking about. `Invoke VBA` operates on the workbook open inside the surrounding `Excel Process Scope` — different scope = different workbook = unrelated data.
+- **Code file** — the `CodeFilePath` in evidence resolves to the macro source the user is asking about. A `.txt`/`.vba`/`.bas` file path that no longer exists on the robot machine, or a stale path checked into source control, is a different file than the one the user has open locally.
+- **Entry method** — the `EntryMethodName` in evidence matches the macro the user reports calling. Don't substitute a similarly-named macro.
+- **Robot / machine identity** — the robot account and the machine where Excel installed match the one the user reports. Excel security settings (Trust Center, Trust access to VBA project) are per-user-per-machine, so evidence from a different host is not transferable.
+- **Office version** — the Excel/Office version installed on the robot machine matches the one the user reports. Multiple Office versions on the same host produce COM dispatcher ambiguity unrelated to a single-version user's experience.
+- **Timestamp** — the failure occurred during the time window the user reported. Load-bearing for COM-interop investigations (transient `0x80010100` errors may not reproduce on demand) and for Trust Center investigations (the setting may have been changed since).
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+### Invoke VBA
+
+1. **Workflow source** — read the `InvokeVBAX` activity node from the surrounding `.xaml` to capture the literal values of `CodeFilePath`, `EntryMethodName`, and the expression bound to `EntryMethodParameters`. Property panel summaries truncate; the XAML is authoritative.
+2. **Code file contents** — read the macro source at the resolved `CodeFilePath`. Required to verify the `Sub`/`Function` declaration name and signature against `EntryMethodName` and `EntryMethodParameters`. Check encoding: a UTF-8 BOM, UTF-16, or stray control character will compile-fail.
+3. **Excel Trust Center setting** — `File > Options > Trust Center > Trust Center Settings > Macro Settings > "Trust access to the VBA project object model"` on the robot machine, under the same Windows user that runs the robot. The setting is per-user-per-machine and per Office install.
+4. **Excel state at failure time** — whether Excel.exe was running, whether any modal dialog was open (recover-unsaved-files banner, license activation, macro-warning bar, "trust this file" prompt), and whether `Visible = True` was set on the surrounding `Excel Process Scope` (without it, dialogs are invisible to the user but still block the macro).
+5. **Office installation inventory** — number of Office versions installed on the host (Microsoft 365, perpetual Office 2016/2019/2021, click-to-run vs. MSI), and whether the installed bitness (32-bit vs. 64-bit) matches the robot process bitness.
+
+### Lookup Range
+
+1. **Workflow source** — read the `ExcelLookUpRange` / `LookUpRangeX` node from the `.xaml` to capture the literal `Range`, `Value` expression, `SheetName`, and `Output` variable, plus whether the activity is inside an `Excel Application Scope` / `Use Excel File` container. Distinguish an empty-string `Range = ""` from a genuinely blank `Range` field — they behave differently.
+2. **Activity output, not just errors** — for the active-filter scenario the activity throws nothing; the symptom is a null/empty/wrong `Output`. Trace the `Output` variable downstream rather than only grepping for a `Lookup Range` error line.
+3. **Workbook sheet/range inventory** — the actual tab names in the target workbook (to compare against `SheetName`) and whether any named range/table the activity references is defined (`Formulas > Name Manager`).
+4. **Filter state** — whether the target worksheet has active AutoFilters / hidden rows that exclude the search value. Requires inspecting the workbook (or asking the user) — not visible in the job log.
+5. **Excel-installed check** — for the Interop init failure, whether Microsoft Excel is installed on the execution host (`Control Panel > Programs and Features`, or the `App Paths\excel.exe` registry key) and whether the robot is a Linux/container host that cannot run Interop at all.
+6. **File-lock state** — whether the workbook is open interactively, held by an orphaned `EXCEL.EXE`, touched by a concurrent job, or locked by a sync/AV client at the failure time.
+7. **Formula-cell state of the target** — whether the cell the search value should match is the *computed* result of an Excel formula (and not a static value). Note any volatile functions, cross-sheet/external references, or add-in dependencies in the formula. Required to distinguish a formula-cell silent miss from the active-filters or type-mismatch causes.
+
+## Testing Prerequisites
+
+### Invoke VBA
+
+When testing hypotheses for `Invoke VBA` issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — confirm the faulted activity is `UiPath.Excel.Activities.Business.InvokeVBAX` (display name "Invoke VBA") and not a generic `Excel.Macros` or `Invoke Macro` activity, which run different code paths.
+2. **Macro source file path** — exact path bound to `CodeFilePath`, resolved against the robot's working directory at job run time (relative paths are resolved against the project folder, not the workbook folder).
+3. **Macro source file contents** — the full text of the `.txt`/`.vba`/`.bas` file at that path. Verify it contains a `Sub <Name>` or `Function <Name>` declaration matching `EntryMethodName`, no syntax errors, no encoding artifacts.
+4. **Entry method name and signature** — exact `EntryMethodName` string, exact `Sub`/`Function` declaration in the code file (name, parameter count, parameter types). VBA is case-insensitive but parentheses and trailing whitespace are not.
+5. **Parameter expression** — the expression bound to `EntryMethodParameters`. Confirm it evaluates to an `IEnumerable<Object>` (typically a `New Object() {...}` array, not a raw string or single value).
+6. **Excel Process Scope properties** — `Visible` setting, `ShowOnPrompt` / dialog handling, workbook path, password (if any), and whether the scope runs with `WorkbookPath` set or against an already-open workbook.
+7. **Trust Center setting** — captured directly from the robot machine under the running user account. The setting is not visible in Orchestrator and cannot be inferred from job logs alone — the user (or someone with desktop access on the host) has to check it.
+8. **Package version** — `UiPath.Excel.Activities` version. The exception messages produced by `InvokeVBAX` have shifted across major versions (notably the 2.20 → 2.22 and 6.x rewrites).
+9. **Office version and bitness** — the exact Excel version installed on the robot machine and whether it is 32-bit or 64-bit. Mismatch with robot bitness is a known cause of COM dispatcher errors.
+
+### Lookup Range
+
+When testing hypotheses for `Lookup Range` issues, gather and verify these before drawing conclusions:
+
+1. **Activity surface** — confirm classic `UiPath.Excel.Activities.ExcelLookUpRange` (Interop, inside `Excel Application Scope`) vs modern `UiPath.Excel.Activities.LookUpRangeX` (inside `Use Excel File` / `Excel Process Scope`). The Excel-not-installed failure is most acute on the classic Interop surface.
+2. **Range / Value / SheetName** — the literal `Range` (blank vs `""` vs A1 reference), the search `Value` expression and its .NET type, and the `SheetName`. These drive the invalid-range, null-reference, and active-filter hypotheses.
+3. **Output disposition** — whether the activity threw or returned a null/empty/wrong cell address. A clean return with no match points at active filters or a value type/whitespace mismatch, not an exception path.
+4. **Workbook sheet names and named ranges** — the actual tabs and defined names, compared character-for-character against `SheetName` and any named-range reference.
+5. **Worksheet filter state** — active AutoFilters or hidden rows on the target sheet at run time.
+6. **Excel installed + reachable** — whether desktop Excel is installed on the host (for Interop) and whether the workbook file is currently locked by another process.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/overview.md

@@ -0,0 +1,43 @@
+# Excel Activities
+
+Activities from the `UiPath.Excel.Activities` package for automating Microsoft Excel on Windows. Two execution surfaces coexist: modern Excel-scope activities that operate inside an `Excel Process Scope` and drive a real Excel.exe instance via COM interop, and legacy workbook activities that read/write `.xlsx` files directly through OpenXML without Excel installed. `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) is COM-only — it requires Excel.exe and a workbook handle.
+
+## How Invoke VBA Executes
+
+`Invoke VBA` reads a macro from an **external code file** (`.txt`, `.vba`, `.bas`) at the configured `CodeFilePath`, injects it into the workbook's `VBProject` at runtime, calls the function named in `EntryMethodName`, then removes the injected module. Behaviour chain:
+
+1. Resolve the active workbook handle from the surrounding `Excel Process Scope`
+2. Read the macro source text from `CodeFilePath`
+3. Add a new VBA module to the workbook via `Workbook.VBProject.VBComponents.Add` (this step requires Excel's "Trust access to the VBA project object model" setting to be enabled)
+4. Run `Application.Run("<EntryMethodName>", <EntryMethodParameters>)`
+5. Remove the injected module
+
+Failures can originate at any layer — Excel security policy (step 3), code file content (step 2), entry method resolution (step 4), parameter marshaling (step 4), or COM interop with Excel itself (steps 1, 3, 4). Knowing which layer produced the error narrows the investigation.
+
+## Key Activities
+
+- **Invoke VBA** (`InvokeVBAX`, display name "Invoke VBA") — execute a VBA macro stored in an external code file against the workbook currently open in the parent `Excel Process Scope`. Properties: `CodeFilePath` (path to `.txt`/`.vba`/`.bas` containing the macro source), `EntryMethodName` (name of the `Sub` or `Function` to invoke), `EntryMethodParameters` (`IEnumerable<Object>` of arguments), `Output` (return value when `EntryMethodName` points to a `Function`).
+- **Lookup Range** — find the cell address of a value within a worksheet range. Two surfaces: classic `UiPath.Excel.Activities.ExcelLookUpRange` (inside an `Excel Application Scope`, **Excel Interop / COM only**) and modern `UiPath.Excel.Activities.LookUpRangeX` (inside a `Use Excel File` / `Excel Process Scope`). Properties: `Range` (A1 range to search; leave **blank** — not `""` — to search the whole used range), `Value` (the value to find), `SheetName` (target sheet), `Output` (the matched cell address). Searches only *visible* cells, so active AutoFilters change the result.
+
+## Common Failure Patterns
+
+- **Trust access to VBA project denied** — `Invoke VBA` faults the first time it tries to inject a module because Excel's "Trust access to the VBA project object model" setting is disabled. Surfaces as `Programmatic access to Visual Basic Project is not trusted` or a wrapped variant. The error is a security-policy block, not a code defect.
+- **Macro source file unreadable or malformed** — `Invoke VBA` faults reading or compiling the macro source. Surfaces as `Cannot run the macro`, `Compile error`, `Syntax error`, or `Sub or Function not defined`. Causes: code not wrapped in a `Sub`/`Function` block, non-UTF-8 encoding with hidden BOM/control characters (common when the file was generated inside Studio), missing or wrong `CodeFilePath`, code authored in an `.xlsm` rather than an external text file.
+- **Entry method name mismatch** — `Invoke VBA` faults with `Cannot run the macro '<name>'. The macro may not be available in this workbook` or `Sub or Function not defined` because `EntryMethodName` does not match a `Sub`/`Function` declared in the code file. Causes: typo, case mismatch (VBA identifiers are case-insensitive in source but UiPath passes the string through to `Application.Run`, which has been observed to reject case-mismatched names in some Excel versions), parentheses appended to the name (`MyMacro()` instead of `MyMacro`), or the macro is nested inside another `Sub`.
+- **Parameter type or shape mismatch** — `Invoke VBA` faults marshaling `EntryMethodParameters` into the COM call. Surfaces as `Type mismatch`, `Wrong number of arguments or invalid property assignment`, or a Studio freeze during property edit. Causes: `EntryMethodParameters` not an `IEnumerable<Object>` (e.g., a raw `String` or `Object` typed directly into the property panel), wrong arity (count mismatches the macro signature), or values typed inline in the property window instead of built via an `Assign` activity.
+- **COM interop with Excel failed** — `Invoke VBA` (or the surrounding Excel activity) faults with an HRESULT from the COM layer. The most common is `0x80010100 RPC_E_SYS_CALL_FAILED` ("The system call failed"). Causes: Excel busy with a blocking modal dialog (license prompt, recover-unsaved-files banner, macro-warning bar), Excel.exe hung, multiple Office versions installed, or a 32-bit/64-bit Office mismatch with the robot process.
+
+### Lookup Range
+
+- **Excel not installed / Interop init failure** — classic `Lookup Range` launches Excel.exe via the Interop API and faults at startup on a host with no Excel. Surfaces as `Excel is not installed`, `REGDB_E_CLASSNOTREG` (`80040154`), or `Could not load ... Microsoft.Office.Interop.Excel`. Migration target on Excel-less hosts: Workbook `Read Range` (OpenXML) + `Lookup Data Table`.
+- **Silent miss from active filters** — `Lookup Range` searches only visible cells, so active AutoFilters/column filters that hide the target row make it return null/empty with no error. A downstream null fault is the first visible symptom.
+- **Workbook locked / file in use** — opening the workbook faults with `The process cannot access the file because it is being used by another process` / `locked for editing`. Causes: file open interactively, an orphaned `EXCEL.EXE` holding the handle, a concurrent job, or a sync/AV client. Distinct from the COM `0x80010100` dispatcher failure above.
+- **Object reference not set (sheet/range missing or no scope)** — `NullReferenceException` when the `SheetName` does not exist (typo/rename/case), a named range/table is undefined, or the activity runs outside an `Excel Application Scope` / `Use Excel File` so there is no workbook context.
+- **Invalid range syntax or value misconfiguration** — `Range` set to an empty-string `""` instead of left blank (whole-sheet search is *blank*, not `""`), a malformed A1 reference, unescaped wildcards (`*`/`?`/`~`) in the search `Value`, or a type mismatch (text-vs-number, stray whitespace) that makes a present value fail to match.
+- **Silent miss against a formula cell** — the search target is the *computed* result of an Excel formula and the Interop read can fail or read an unrefreshed value. `Lookup Range` returns null/wrong even though the displayed cell text matches the search value. Common with volatile formulas, cross-sheet / external references, and add-in-dependent calculations. The fix is to either freeze the cell to a static value (`Copy > Paste Special > Values`) or move off Interop to the Workbook `Read Range` + `Lookup Data Table` path, which reads cached values rather than re-evaluating.
+
+## Package
+
+NuGet: `UiPath.Excel.Activities`
+
+Version-specific bugs are documented in the relevant playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/invoke-vba-code-file-path.md

@@ -0,0 +1,46 @@
+---
+confidence: medium
+---
+
+# Invoke VBA — Cannot Run Macro / Code File Unreadable
+
+## Context
+
+What this looks like:
+- Activity `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) faults while loading or compiling the macro source from the external code file
+- Error message contains one of: `Cannot run the macro`, `Compile error`, `Syntax error`, `Sub or Function not defined`, `Expected: end of statement`, or a generic VBA compiler error citing a line number in the injected module
+- Job faults synchronously the moment `Invoke VBA` runs, after `Excel Process Scope` opened successfully and before any macro logic executes
+
+What can cause it (more than one may apply):
+- **Code not wrapped in a `Sub`/`Function` block** — the file contains bare VBA statements at the top level. `Invoke VBA` injects the file's contents as a module, which only accepts procedure declarations at the top level.
+- **Non-UTF-8 encoding or hidden control characters** — the code file is UTF-16, has a UTF-8 BOM, or contains zero-width / non-printable characters that the VBA compiler rejects. Common when the file was created via UiPath Studio's built-in editor on Windows (which may save as UTF-16 LE with BOM) or copied from a Word document.
+- **`CodeFilePath` does not resolve** — the path points to a file that does not exist on the robot machine, is locked by another process, or is a relative path that resolves against the project folder rather than the workbook folder.
+- **VBA syntax errors in the macro source** — typos, missing `End Sub`, mismatched parentheses, references to undefined VBA functions.
+- **Code authored inside an `.xlsm`** — the user wrote the macro inside the workbook's VBA editor and pointed `CodeFilePath` at the `.xlsm`. `Invoke VBA` does not read macros from an `.xlsm`; the source must be in an external `.txt`/`.vba`/`.bas` file.
+
+## Investigation
+
+1. Read the `InvokeVBAX` node from the workflow `.xaml` and capture the literal `CodeFilePath` value.
+2. Resolve the path against the robot's working directory at job run time. Confirm the file exists on the robot machine and is readable by the robot's Windows user.
+3. Open the file and confirm:
+   - It is a plain-text file (`.txt`, `.vba`, or `.bas`), not an `.xlsm` workbook.
+   - The first non-blank line is a `Sub <Name>` or `Function <Name>` declaration. There are no bare executable statements outside a procedure block.
+   - The declared procedure name matches `EntryMethodName` exactly (apart from case — VBA is case-insensitive in source, but see the entry-method playbook for `Application.Run` caveats).
+4. Check the file encoding (open in Notepad++ / VS Code status bar, or run `file` on the path from WSL/Git Bash). It must be UTF-8 without BOM, or pure ASCII. UTF-16 or UTF-8-with-BOM will compile-fail.
+5. If steps 1–4 all pass, copy the file's contents into Excel's VBA editor manually and try `Run` — if VBA itself reports a compile error there, the macro source has a defect independent of UiPath.
+
+## Resolution
+
+- **If `CodeFilePath` does not resolve on the robot machine** — fix the path. Prefer an absolute path that is reachable from the robot, or place the code file inside the project folder and reference it with a project-relative path. Re-deploy and re-run.
+- **If the code is not wrapped in a `Sub`/`Function`** — edit the code file and wrap the executable statements:
+  ```vb
+  Sub MyMacro()
+      ' existing statements
+  End Sub
+  ```
+  Then set `EntryMethodName` to `MyMacro` on the activity.
+- **If the file is UTF-16, has a UTF-8 BOM, or contains hidden control characters** — re-create the file externally (Notepad, Notepad++, VS Code). In Notepad++, set `Encoding > Convert to UTF-8` (without BOM); in VS Code, click the encoding indicator in the status bar and select `Save with Encoding > UTF-8` (no BOM). Replace the original file at `CodeFilePath`.
+- **If the macro source has VBA syntax errors** — fix them in the external file, validating by opening the file's content in Excel's VBA editor (`Alt+F11`) and pressing `Debug > Compile VBAProject`. Re-save and re-run.
+- **If the user wrote the macro inside an `.xlsm`** — extract the macro to an external `.txt` or `.vba` file: open the `.xlsm`, press `Alt+F11`, copy the `Sub`/`Function` text out of the VBA editor, paste into a new text file, save as UTF-8 (no BOM), and point `CodeFilePath` at that file.
+
+If after all of the above the error still cites a missing `Sub` or `Function`, the failure is not in the code file — see the entry-method-name playbook.