docs(uipath-troubleshoot): Python Activities package + RunScript playbooks (+3 scenarios)

[Stefan-Virgil]

What

Adds a python-activities reference package to uipath-troubleshoot so investigations into UiPath.Python.Activities failures match dedicated playbooks instead of falling back to the low-confidence runtime-exceptions pointer, plus 3 faithful-replay coder-eval scenarios.

UiPath.Python.Activities runs Python out-of-process and marshals objects over an IPC pipe, so most failures are environment/config mismatches the job log hides rather than workflow-logic bugs. The package overview documents that model (Path = install folder, Target bitness, Version, Library path, WorkingFolder).

Playbooks (cover the error matrix)

Playbook	Confidence	Signature
invoke-python-method-pipe-is-broken	Medium	Pipe is broken — out-of-process host died (missing pip module / unhandled exception / hard sys.exit / stdout flood). Python traceback is swallowed.
python-path-not-valid	High	The specified Python path is not valid — Path points at python.exe (the file) or the WindowsApps\python Store alias instead of the install folder.
python-scope-architecture-version-mismatch	Medium	One or more errors occurred / BadImageFormatException — Target/Version/Library path bitness mismatch or missing .NET Desktop Runtime.
working-folder-relative-path	Medium	Script runs but reads/writes wrong files — relative paths resolving against the robot's per-package WorkingFolder CWD.

Router updated in references/summary.md (namespace UiPath.Python.Activities).

Tests — 3 scenarios, validated locally

Each replays a faulted unattended job against the uip CLI mock and grades against a known-good RESOLUTION.md (skill_triggered + RESOLUTION-anchored llm_judge, per the skill's tests/tasks CLAUDE.md contract).

Scenario	Result
python-pipe-broken-missing-module (pandas absent from robot interpreter)	✅ SUCCESS, score 1.000
python-scope-path-is-file (Path = ...\python.exe)	✅ SUCCESS, score 1.000
python-scope-arch-mismatch (Target=x86 vs 64-bit install)	✅ SUCCESS, score 1.000

Passing-run claim: all 3 run under experiments/default.yaml (tempdir), 3/3 SUCCESS, weighted_score 1.000, judge rationales confirm each agent matched the correct playbook and converged on the reference root cause + fix.

/lint-task: 3/3 OK. coder-eval plan: all valid.

🤖 Generated with Claude Code

[github-actions]

Claude finished @Stefan-Virgil's task in 3m 35s —— View job

---

Coder-eval task lint (advisory)

3 task YAMLs changed; verdict counts: 0 Critical, 0 High, 0 Medium, 0 Low, 3 OK.

Rubric: .claude/commands/lint-task.md. This check is advisory and never blocks merge.

Evidence of passing run

✅ Author confirms passing run: "Passing-run claim: all 3 run under experiments/default.yaml (tempdir), 3/3 SUCCESS, weighted_score 1.000, judge rationales confirm each agent matched the correct playbook and converged on the reference root cause + fix."

Per-task lint

tests/tasks/uipath-troubleshoot/python-pipe-broken-missing-module/task.yaml — verdict: OK

tests/tasks/uipath-troubleshoot/python-scope-path-is-file/task.yaml — verdict: OK

tests/tasks/uipath-troubleshoot/python-scope-arch-mismatch/task.yaml — verdict: OK

Within-PR duplicates

No duplicate clusters detected. All three tasks share the same YAML scaffold (sandbox config, skill_triggered + llm_judge criteria), but exercise materially distinct Python Activities failure modes — different error signatures, different root causes, different playbooks, different fixes:

Task	Error signature	Root cause
python-pipe-broken-missing-module	Pipe is broken at Invoke Python Method	Missing pip module in robot interpreter → out-of-process host dies
python-scope-path-is-file	The specified Python path is not valid	Path set to python.exe (file) instead of install folder
python-scope-arch-mismatch	One or more errors occurred / BadImageFormatException	Target=x86 vs 64-bit Python install → bitness mismatch

This is scaffold reuse, not duplication.

Conclusion

✅ All changed tasks pass the rubric. Evidence of passing run confirmed.

Notes:

• All three tasks correctly follow the uipath-troubleshoot CLAUDE.md contract: exactly skill_triggered + llm_judge criteria, no brittle command_executed/file_exists checks.
• llm_judge criteria are backed by ground truth (include_reference: true → RESOLUTION.md), with detailed multi-level scoring rubrics.
• Run limits are in the canonical run_limits: block (not deprecated agent: location).
• No env_packages / no redundant @uipath/cli installs.
• Tags follow closed vocabulary and match established sibling patterns (mode:diagnose, lifecycle:discover, faulted-jobs, orchestrator, python-activities, rpa).
• allowed_tools correctly extends experiment defaults with AskUserQuestion + TodoWrite.

[github-actions]

Claude finished @Stefan-Virgil's task in 3m 33s —— View job

---

PR Review: Python Activities RunScript Playbooks

• Read review criteria and project conventions
• Analyze full diff (51 files, +1864 lines)
• Review skill reference files (playbooks, overview, investigation guide)
• Review test task files (3 scenarios)
• Check router update in summary.md
• Verify links, structure, and conventions
• Post findings

---

Summary

Adds a complete python-activities reference package (overview, investigation guide, presentation rules, summary, 4 playbooks) to uipath-troubleshoot, covering the UiPath.Python.Activities error matrix (pipe-broken, path-not-valid, architecture-mismatch, working-folder). Router entry added to references/summary.md. Three e2e coder-eval scenarios with synthetic fixtures, process snapshots, and RESOLUTION.md ground truths accompany the playbooks.

Change-by-Change Review

1. references/activity-packages/python-activities/overview.md

OK

Well-structured package overview documenting the out-of-process execution model, key activities, and common failure patterns. The two-property model ("interpreter is external" + "Python side is black box") is a strong framing for the agent. Links to package documentation are appropriate.

2. references/activity-packages/python-activities/investigation_guide.md

OK

Thorough data-correlation rules and testing prerequisites. The "Out-of-band confirmation" section correctly identifies that pip-list/bitness/standalone-run evidence lives on the robot host, not in the job log — critical for preventing the agent from blocking on missing log data.

3. references/activity-packages/python-activities/presentation.md

OK

Compact, actionable presentation rules covering display names, interpreter identification, error quoting, bitness naming, and run-surface terminology. Good token economy.

4. references/activity-packages/python-activities/summary.md

OK

Clean playbook router with confidence levels. Links to investigation guide and all four playbooks verified.

5. references/activity-packages/python-activities/playbooks/invoke-python-method-pipe-is-broken.md

OK

Medium-confidence playbook covering the hidden-traceback failure family well. Investigation steps correctly prioritize reading the .py imports over the job log (since UiPath swallows the traceback). Resolution covers pip install into the scope's interpreter, try/except wrapping, and general prevention.

6. references/activity-packages/python-activities/playbooks/python-path-not-valid.md

OK

High-confidence playbook. Covers the two classic Path traps (file-not-folder, Store alias) plus the per-user install edge case. Investigation and resolution steps are clear and copy-paste ready.

7. references/activity-packages/python-activities/playbooks/python-scope-architecture-version-mismatch.md

OK

Medium-confidence playbook covering bitness, version, library-path, and .NET runtime causes. The out-of-band bitness-check command (struct.calcsize('P')*8) is a good inclusion.

8. references/activity-packages/python-activities/playbooks/working-folder-relative-path.md

OK

Medium-confidence playbook for the CWD-divergence class. Correctly identifies %LocalAppData%\UiPath\Packages\... prefix as the smoking gun. Resolution covers both workflow-side (WorkingFolder) and script-side (os.path.dirname(__file__)) approaches.

9. references/summary.md — router update

OK

New ## Python Activities section added with namespace, description, and links. Follows the existing format of the other package sections. All links verified.

10. Test scenario: python-pipe-broken-missing-module

OK

Task YAML follows conventions: task_id matches skill-troubleshoot-*, tags include uipath-troubleshoot first + e2e + mode:diagnose + lifecycle:discover, run_limits uses the canonical block, sandbox.mock_path_dirs is set, no env_packages. Two criteria only (skill_triggered + llm_judge) per the CLAUDE.md contract. Judge rubric is detailed with a 5-tier scoring scale tied to the RESOLUTION.md ground truth. Process snapshot (Main.xaml, parse_invoice.py, project.json) is internally consistent — the XAML references parse_invoice.py, the script imports pandas, the mock logs show the pipe break at InvokeMethod_1. Mock fixtures are synthetic and properly scrubbed (MOCK-HOST, placeholder keys).

11. Test scenario: python-scope-path-is-file

OK

Same structural quality as above. The Main.xaml correctly has Path="C:\Program Files\Python311\python.exe" (the deliberate bug), matching the mock job error. Judge rubric correctly identifies the file-vs-folder insight as the decisive chain.

12. Test scenario: python-scope-arch-mismatch

OK

The Main.xaml correctly has Target="x86" against a 64-bit install path. Mock or-jobs-get correctly includes the BadImageFormatException (0x8007000B) inner error. crunch.py uses only statistics (stdlib), correctly ruling out the missing-module cause. Judge rubric handles this differential diagnosis well.

13. All 3 RESOLUTION.md files

OK

Each follows the established structure: Root Cause → What went wrong → Why → Evidence (categorized by source) → Cross-check (differential diagnosis) → Recommended Fix. The cross-checks are particularly valuable — they explicitly rule out the other playbooks, which helps the judge distinguish correct vs. incorrect playbook matches.

14. All 3 README.md files

OK

Each describes what the scenario uncovers, maps to the correct playbook, and documents the fixture layout. Notes on synthetic fixtures are present.

What's Missing

Nothing identified. The PR is well-scoped:

• CODEOWNERS already covers /skills/uipath-troubleshoot/ and /tests/tasks/uipath-troubleshoot/ (line 123-124), which covers the new paths.
• All relative links from summary.md and playbook summary resolve to existing files.
• No cross-skill references.
• No secrets or personal paths (the "*password*" match in project.json is a UiPath logging exclusion filter, not a credential).
• The 4th playbook (working-folder-relative-path) has no test scenario, but this is reasonable — the PR title says "3 scenarios" and the working-folder case is harder to mock (the script succeeds but produces wrong output, requiring a different fixture shape). It could be added in a follow-up.

Area Ratings

Area	Status	Notes
Frontmatter	OK	N/A — this PR adds reference files and tests, not a new skill. No SKILL.md frontmatter changes.
E2E Tests	OK	3 e2e tasks, all tagged correctly (skill + tier + mode:diagnose + lifecycle:discover), lean success criteria (skill_triggered + llm_judge only), proper run_limits, no env_packages. Passing-run claim in PR body with 3/3 score 1.000.
Skill Body	OK	N/A — no SKILL.md changes.
References & Assets	OK	8 new reference files form a complete package: overview, investigation guide, presentation rules, summary, 4 playbooks. All internally consistent, well-structured, and following the terse documentation style.
Repo Hygiene	OK	CODEOWNERS already covers paths. No secrets. No cross-skill refs. No binary files. Changes scoped to uipath-troubleshoot.

Issues for Manual Review

• Domain accuracy of playbook content — the out-of-process IPC model, Path-is-a-folder semantics, Target bitness behavior, and WorkingFolder CWD defaults are all specific to the UiPath.Python.Activities package. A domain expert should confirm these match the actual package behavior, particularly the assertion that Library path is required for Python > 3.9 on Windows.
• Mock fixture realism — the synthetic job/log fixtures use plausible UiPath API response shapes, but a reviewer familiar with the current uip or jobs get/logs output schema should verify that the fields and structure match the real CLI output (e.g., JobError subobject shape, TraceId field presence).

Conclusion

Clean PR. The reference package is thorough, internally consistent, and follows the established troubleshoot skill patterns. The 3 test scenarios are well-crafted with clear differential-diagnosis rubrics. No issues requiring changes.

Recommendation: Approve.