@uipath/skills 1.197.0 → 1.197.2

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

@@ -1,118 +0,0 @@
-# Evidence Schema
-
-## Directories
-
-| Directory | Purpose | Contents |
-|-----------|---------|----------|
-| `.local/investigations/evidence/` | Interpreted evidence summaries | JSON files with analysis and interpretation |
-| `.local/investigations/raw/` | Raw data dumps | Unprocessed CLI responses, file contents |
-
-Created by: Triage sub-agent, Hypothesis Tester sub-agent
-Read by: All sub-agents, orchestrator
-
-## File naming
-
-### Evidence files (`.local/investigations/evidence/`)
-
-- `triage-initial.json` — initial data from triage (job info, error, etc.)
-- `{hypothesis-id}-{source}.json` — evidence for a specific hypothesis
-  - e.g., `H1-cli-data.json`, `H1-docsai-results.json`, `H2a-source-analysis.json`
-
-### Raw data files (`.local/investigations/raw/`)
-
-- `triage-{command-name}.json` — raw triage CLI response
-- `{hypothesis-id}-{command-name}.json` — raw CLI response for a hypothesis
-  - e.g., `H1-Jobs_GetByKeyByIdentifier.json`, `H1-GetJobTraces.json`
-
-## Structure
-
-Each evidence file:
-
-```json
-{
-  "id": "evidence-unique-id",
-  "hypothesis_id": "H1",
-  "source": "uip_cli | docsai | playbook | user | source_code",
-  "collected_by": "triage | tester",
-  "timestamp": "ISO8601",
-  "query": "What was queried or asked (uip command, docsai query, file path read)",
-  "raw_data_ref": "raw/H1-Jobs_GetByKeyByIdentifier.json",
-  "raw_data_summary": "Condensed summary of what was found (keep under 100 lines)",
-  "interpretation": "What this evidence means for the hypothesis",
-  "elimination_checks": [
-    {
-      "criterion": "what elimination criterion from evidence_needed.to_eliminate was checked",
-      "result": "what the query/check actually returned",
-      "outcome": "passed (hypothesis survives) | failed (hypothesis eliminated) | not_testable (data unavailable)"
-    }
-  ],
-  "execution_path_traced": [
-    {
-      "step": "description of this step in the expected execution path",
-      "expected": "what the hypothesis predicts should have happened",
-      "actual": "what the data actually shows",
-      "verified_by": "which query or data source confirmed this"
-    }
-  ],
-  "needs_user_input": false,
-  "user_question": null
-}
-```
-
-## Signals (triage-initial.json only)
-
-`evidence/triage-initial.json` carries a top-level `signals` array. Signals are the structured inventory of discrete facts triage extracted from gathered data. They are the unified input to playbook matching, hypothesis generation, and hypothesis testing.
-
-```json
-{
-  "signals": [
-    {
-      "name": "exception_class",
-      "value": "System.NullReferenceException",
-      "category": "exception",
-      "source": "raw/triage-job-logs.json"
-    },
-    {
-      "name": "package_version",
-      "value": "UiPath.System.Activities 22.10.5",
-      "category": "package_version",
-      "source": "raw/triage-job-traces.json"
-    },
-    {
-      "name": "asset_exists",
-      "value": true,
-      "category": "entity_state",
-      "source": "raw/triage-resource-assets-list.json"
-    }
-  ]
-}
-```
-
-### Fields
-
-- `name` — short identifier for the signal (e.g., `exception_class`, `error_code`, `asset_exists`, `package_version`). Snake_case, descriptive.
-- `value` — observed value. String, number, or boolean. For boolean signals like `asset_exists`, `true` means "asset is present"; `false` means "asset is absent".
-- `category` — one of: `exception | error_code | http_status | activity_label | entity_state | package_version | runtime_type | error_fragment | cross_product_ref | folder_context`. Use the closest match; do not invent new categories without need.
-- `source` — relative path to the raw file the signal was extracted from. The signal MUST be traceable back to actual observed data.
-
-### Producers and consumers
-
-- **Triage** produces signals while executing plan data-fetch steps. Each fetched response is scanned for signal-worthy facts and entries are appended to `signals`. Triage step E (match playbooks) iterates this array, not the raw files.
-- **Hypothesis generator** reads `signals` to inform what hypotheses to draft. Each generated hypothesis records which signals supported it (see `schemas/hypotheses.schema.md` → `signals_supporting`).
-- **Hypothesis tester** reads `signals` BEFORE its test plan. For each `to_confirm` / `to_eliminate` item, the tester checks whether a signal already resolves it. If yes, the corresponding plan step is `status: skipped` with the signal name in `purpose` — no re-fetch.
-
-### Rules
-
-- One signal per discrete fact. Do NOT combine multiple facts into one signal (`exception_class_and_message` is two signals, not one).
-- Never overwrite or reconcile a signal in place — one `name` = one observed fact. If two raw sources disagree, that is NOT a forbidden state: record each observation as its own signal with a distinct `name` and let the matcher / downstream agents resolve the conflict. The only thing disallowed is mutating an existing signal (see immutability below).
-- Signals are immutable once written. New evidence appends new signals; existing signals don't get rewritten.
-
-## Rules
-
-- **Raw data MUST be written to `.local/investigations/raw/` immediately** — write the full response to a raw file BEFORE summarizing
-- **Never keep raw data in context** — write it to a raw file, then read it back only if needed for analysis. Do not hold CLI responses or log dumps in the agent's working memory.
-- Evidence files contain summaries and interpretation only; they reference raw files via `raw_data_ref`
-- If a sub-agent needs user input, set `needs_user_input: true` and `user_question` to the question
-- The orchestrator reads evidence files (not raw files) to make decisions
-- Evidence files are immutable once written — new evidence gets a new file
-- Raw files are immutable once written — they are the source of truth for what was actually returned

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

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

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

@@ -1,27 +0,0 @@
-# Scope Check Schema
-
-File: `.local/investigations/scope-check.json`
-
-Created by: Scope Checker sub-agent
-Read by: Orchestrator
-
-## Structure
-
-```json
-{
-  "checked_after": "triage | test",
-  "current_domains": ["orchestrator"],
-  "missing_domains": [],
-  "unnecessary_domains": [],
-  "reasoning": "Why domains should be added/removed, or why current scope is correct"
-}
-```
-
-## Rules
-
-- Scope Checker writes this file after analyzing evidence against known product domains
-- Orchestrator reads it to decide whether to expand or narrow scope
-- `checked_after` records which phase triggered the scope check
-- `missing_domains` lists domains that should be added based on evidence
-- `unnecessary_domains` lists domains that are only reporting layers with no relevant playbooks
-- If both `missing_domains` and `unnecessary_domains` are empty, the current scope is correct

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

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