docs(uipath-rpa): workflow authoring rules, rerun-safe REFramework, XAML and activity pitfalls, uip rpa publish - #3782

Claude finished @danmunteanu1's task in 6m 2s —— View job

PR Review: docs(uipath-rpa) — workflow authoring rules, rerun-safe REFramework, XAML pitfalls, publish

• Read review criteria (.github/code_review.md) and project conventions
• Read full diff (origin/main...HEAD)
• Read existing PR conversation
• Review changed files in full context
• Check skill-specific items (links, cross-skill refs, secrets, CODEOWNERS)
• Post review findings

Summary

Substantial documentation update to skills/uipath-rpa/ — 33 files, +341/−224 lines. Replaces uip or packages upload / uip or libraries upload with the unified uip rpa publish, adds new XAML pitfalls (InvokeCode Language default, Finally cross-file semantics, array x: prefix, whitespace collapse, OCR CoreIPC, folder-naming CS0101, database activity gotchas), corrects While/DoWhile/ForEach Condition type from InArgument<bool> to Activity<bool>, adds REFramework rerun-safety guidance, adds MultipleAssign to the activity card, adds workflow-file authoring rules (Common Rules 4a/4b), and fixes CodedWorkflowBase across all partial-class examples.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md (+12/−9)

Severity: OK

Clean changes: new Common Rules 4a (author with file tools) and 4b (write a file only for an invocable unit) fit naturally after Rule 4. Try/Catch guidance refined from "around every external interaction" to "each unit whose failure you handle differently" — consistent with the error-handling guide update. uip or packages upload → uip rpa publish aligns with the CLI catalog. Studio Web constraint for coded/C# projects added to Rule 2a. dotNetVersion mismatch guidance added. project close replaces "host restart" for clearing CS0246.

Section pointer from the Task Navigation table now uses § targeted lookups to specific anchors (environment-setup.md#step-01-establish-project-root, #step-03-creating-a-new-project) — both resolve correctly.

2. references/cli-reference.md (+27/−17)

Severity: OK

The uip rpa publish section is well-structured: destination flags with error messages, the Publishable test-case gate, 409 duplicate-version error. rpa publish confirmed in the CLI catalog (assets/uip-catalog-snapshot.json line 1424). The old commands (or packages upload, or libraries upload) still exist in the catalog but aren't retired — the PR correctly makes rpa publish the recommended path without claiming the old ones are gone. PackagePath vs OutputPath correction, 8.3 short-path pitfall, entry-points.json/bindings_v2.json build artifacts, cleanup --dry-run for unused deps — all substantive.

3. references/xaml/common-pitfalls.md (+100/−87)

Severity: OK

The largest change and the most consequential. Key corrections/additions:

• InvokeCode Language default — changed from "infers from project" to "defaults to VBNet". This is a major correction; the old guidance ("omit Language, it's inferred") would cause C# code to compile as VB.
• InvokeCode Code child element — changed from "silent no-op" to the more precise "line breaks collapse" with the // comment swallowing explained. The <x:String xml:space="preserve"> workaround noted.
• Finally cross-file semantics — reverses the prior claim ("Finally DOES run when the Catch rethrows"). The new guidance is detailed and internally consistent: a rethrow that an outer Try/Catch in the same file catches still runs the inner Finally.
• Coded source file types in XAML — changed from "cannot reference" to "need a namespace import and assembly reference". Major correction with <ProjectName>.Core assembly, InvokeMethod for void helpers, and project close for reload.
• Array types — consolidated from three sections (Array Types in Variable, Generic Type Arguments Cannot Wrap Array Types, plus inline InArgument<Object[]> discussion) into one paragraph under the existing x: prefix section. The key insight: s:Object[] works everywhere x:Object[] doesn't. The InvokeMethod fallback for ParamArray is dropped as unnecessary.
• New sections: OCR CoreIPC check, AppendLine line-break semantics, CopyFolderX into vs as, DeleteFileX raises on missing, folder-naming CS0101, whitespace collapse / xml:space="preserve", database activity gotchas, callee out/InOut arguments on fault. All are specific, testable pitfalls.
• InvokeWorkflowFile arguments — changed from "Dictionary wrapper silently cleared by Studio" to "both forms bind the same; prefer direct children". Removes the wrong "Studio silently clears" claim.
• Assembly references — rewritten from a catch-all "missing assembly" list to "Studio requires, CLI doesn't check" with the System.Collections + <ProjectName>.Core pattern.

4. references/error-handling-guide.md (+7/−5)

Severity: OK

Isolated invoke type preservation corrected (rule 5), Try/Catch granularity guidance refined, Check App State row added to the mechanism table, ContinueOnError on InvokeWorkflowFile pitfall added. The Finally rule 5 here is consistent with common-pitfalls.md.

5. references/reframework-guide.md (+27/−3)

Severity: OK

New subsections: Init/Close rerun safety, template test cases falling behind, Should Stop inside looping Get Transaction Data, End Process not faulting the job. The context-object pattern for non-UI resources (point 3 under Init/Close) correctly cross-references the new common-pitfalls.md § Out and InOut Arguments When the Callee Faults. Checklist items updated to reference the new sections.

6. references/common-activity-card.md (+51/−3)

Severity: OK

MultipleAssign entry is thorough: Windows-only platform constraint, Legacy assembly variant, list-order semantics, C# binding note. Count updated from 13 to 14 activities; the card entry list matches the actual headings (verified: 14 entries, 14 ### sections). Assign notes updated to reference MultipleAssign for consecutive assignments.

7. references/common-pattern-card.md (+6/−8)

Severity: OK

InvokeWorkflowFile snippet changed from Dictionary-wrapped to direct-children form (consistent with the pitfall correction). InvokeCode snippet gets Language="VBNet" (consistent with the default-is-VBNet correction). Notes updated for both.

8. references/coded/codedworkflow-reference.md (+8/−6) and assets/codedworkflow-template.md (+4/−2)

Severity: OK

CodedWorkflowBase added to every partial-class declaration. The explanation of why it's needed (build compiles without a base → CS0103, CS1503) is clear. Templates and reference doc are consistent with each other.

9. references/coded/operations-guide.md (+7/−6)

Severity: OK

All partial class CodedWorkflow references updated to include : CodedWorkflowBase. The coded base partials regeneration procedure updated from "delete + restart + validate" to "delete + project close + validate" — consistent with SKILL.md and the coded troubleshooting table.

10. references/data-manipulation-guide.md (+9/−11)

Severity: OK

The C#-expression XAML escalation path rewritten: coded source file helper method is now a valid option (was previously stated as impossible). Three escalation options instead of two. The "XAML cannot reference coded types" claim removed — correctly, since it was wrong. "Source file vs workflow" paragraph updated to reflect that helpers are callable from expressions.

11. Activity docs (DoWhile, While, ForEach, AddDataRow, AppendLine, CopyFolderX, InvokeCode, InvokeWorkflow, KillProcess, O365 GetEmails, While 26.4, DoWhile 26.4)

Severity: OK

All corrections are specific and internally consistent: InArgument wrapper removed from While/DoWhile Condition, x:Object[] → s:Object[] in AddDataRow, Language attribute added to InvokeCode examples, KillProcessApplyOn enum values corrected to match the actual names, ForEach.Condition and ForEach.Values documentation updated, OrderBy on GetEmails documented as non-functional.

12. Other reference updates (environment-setup, testing-guide, library-authoring-guide, coded-vs-xaml-guide, uia-starter-guide, legacy files, csharp-activity-binding-guide, xaml-basics-and-rules, execution-maps-guide)

Severity: OK

All consistent with the core changes: CodedWorkflowBase in environment-setup, Dictionary-wrapper removal in testing-guide, publish replacing upload in library-authoring-guide, XAML-invoking-coded argument naming in coded-vs-xaml-guide, upload → publish in uia-starter-guide, s:Object[] and InvokeCode attribute form in legacy files, InArgument<Object> literal trap clarified in csharp-activity-binding-guide, assembly-references cross-link in xaml-basics-and-rules, batched gate and OR definition updates in execution-maps-guide.

13. references/legacy/testing-guide.md (+11/−11)

Severity: OK

InvokeCode Code changed from child-element form (literal newlines) to attribute form with `` line breaks — consistent with the InvokeCode pitfall correction. Language="VBNet" added. The `\n` pattern (entity-escaped newline for the runtime plus a real newline for source readability) is valid XML.

What's Missing

• Duplication between AppendLine.md and common-pitfalls.md § AppendLine: both describe the same line-break-before-text behavior, BOM behavior, and empty-file threshold in similar detail. The pitfall entry adds coping advice (split on breaks, strip BOM) that justifies its existence, but the overlap is above a bridging sentence. Consider trimming the pitfall to the "how to cope" angle and pointing at AppendLine.md for the mechanics. (Low)
• or packages upload / or libraries upload not added to cli-renames.md: the PR replaces all references to these commands with rpa publish, but doesn't add them to the retired-verbs table in .claude/rules/cli-renames.md. They still exist in the CLI catalog so they may not be formally retired — but if the intent is that agents should never use them, a retirement entry would help the linter catch future drift. (Low — depends on whether UiPath has formally deprecated these verbs or just added a preferred alternative)

Area Ratings

Issues for Manual Review

• Finally cross-file semantics reversal (error-handling-guide.md:66, common-pitfalls.md:350): the prior guidance stated "Finally DOES run when the Catch rethrows (modern, verified)". This PR reverses it to "Finally runs only when the exception is caught inside the same workflow file." This is a significant behavioral claim that changes how agents structure cleanup. The PR description says "verified" but domain experts should confirm the new behavior matches the UiPath runtime.
• Isolated invoke type preservation (error-handling-guide.md:38): previously stated "Isolated invoke loses the type" (BusinessRuleException arrives as System.Exception). Now states the opposite — "Isolated invoke keeps the type." Another reversal of a verified claim. Domain review recommended.
• InvokeCode Language default (common-pitfalls.md:378, InvokeCode.md:8): previously stated "InvokeCode infers the language from the project's expressionLanguage". Now states "defaults to VBNet whatever the project's expression language." The PR removes the "inferred" examples. Domain experts should confirm the actual runtime behavior.
• uip rpa publish destination flags: the flag table (cli-reference.md:498-502) lists --personal-workspace, --folder-path/--folder-key, --shared-libraries, --feed-id — these should be verified against uip rpa publish --help since they're new to this doc.

Conclusion

Clean, well-structured PR with high-quality content additions. The changes are internally consistent across all 33 files — when one file's guidance changes, every file that references the same concept is updated in the same PR. The four behavioral reversals (Finally semantics, Isolated type, InvokeCode Language default, coded source file accessibility from XAML) are the only items that warrant domain-expert confirmation before merge, as they contradict previously "verified" claims. No blocking issues found.

|