Skip to content

Planner: loops, rethrow-only handlers and passed-down values worded by their result; no application handle across a library call - #4690

Open
vlad-coteanu-uipath wants to merge 1 commit into
mainfrom
genome/app-card-lifecycle-loop-tests-code-steps
Open

vlad-coteanu-uipath wants to merge 1 commit into
mainfrom
genome/app-card-lifecycle-loop-tests-code-steps

Conversation

@vlad-coteanu-uipath

@vlad-coteanu-uipath vlad-coteanu-uipath commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Why

Extracted genomes described some source logic by how it works instead of what it does, such as a loop step by step or a catch block that only re-raises. The build then copied those mechanics. Genomes also told libraries to pass the application's window from call to call, which the rebuilt libraries no longer do.

This PR holds the uipath-planner changes. The other skills' changes from the same migrations are in #4559 (uipath-genome) and #4551 (uipath-rpa).

How the genome describes source logic (genome-format-guide.md)

A loop that only computes, selects or tests is described by its result. If a loop only fills a field on every row, copies the matching rows into another table, or sets a flag when a row matches, the genome says what it produces:

  • "the status of every row is …";
  • "the rows of the table where …";
  • "whether the table holds a row where …".

The build then picks the right activity, such as a filter or a lookup. A loop stays a step only when its body does real work: it acts on an application, a file or a queue, or calls another step.
(§ Workflow)

A catch that only rethrows is not error handling. A handler that catches a failure and immediately raises the same failure, unchanged, does nothing, so the genome writes no Error Handling entry for it; an entry would lead the build to add an empty Try/Catch. A handler that logs, cleans up, retries, changes the failure or decides something before rethrowing is described by what it does.
(§ Error Handling)

A value passed down only to reach the place that uses it is read there. Sources often read the machine name or user name once at the start and pass it through three workflows to the one step that needs it. Such a value is the same wherever it is read, so the genome lets that step read it itself instead of adding an argument to every workflow on the way. A value the caller computes or changes, or one that must stay fixed for the whole run (the run's start time), is passed as an argument.
(§ Interface)

No application handle crosses a library call. An attached application is not state a library passes between calls. Each activity gets the application through its own card where it uses it, and nothing is handed back and forth.
(§ Interface, state kept between calls)

The builder keeps a copy of that last rule (uipath-genome genome-reading-guide.md § Interface). The repo's rules require both copies to change in the same PR, so that one uipath-genome line is here, not in #4559.

Related PRs

Checks

  • Link check, flavor validation and skill status check pass.
  • skills:test was not run locally (no node_modules on this machine); CI runs it.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @vlad-coteanu-uipath's task in 53s —— View job


PR Review: #4690

  • Read review criteria, CLAUDE.md, skill-review rules
  • Read diff and full surrounding files
  • Check flavor overrides, links, cross-skill references, hygiene
  • Post review

Summary

This PR adds three migration rules to uipath-genome. An attach-or-launch becomes one Application Card using its Open/Close options, a backward-jump loop whose body runs before the first test becomes a Do While, and source code doing work that an activity already does becomes that activity. It also adds a uipath-rpa pitfall: an application the workflow drives is opened by its card, not by StartProcess followed by an attach.

Change-by-Change Review

1. skills/uipath-genome/references/composite-interactions-guide.md:34-38

Low

  • The edits are correct and fit the "actions without a control" list. Moving "activate" out of the Window Operations bullet removes a conflict with the keystrokes row (line 22, a source's bring-to-front is `ActivateBefore` ).
  • Naming. Line 37 says "the Activate option", but line 22 calls the same thing ActivateBefore. Lines 34/35 say "Open option" / "Close option" without the enum values. An agent writing XAML or coded workflows needs the literal property and value. Suggest: "OpenMode IfNotOpen", "CloseMode Always" and "ActivateBefore", if those are the values the UIA package docs give. Please confirm against the package's authoring guide.
  • Wording. "Maximise a window, or close one elsewhere" (line 38) is unclear. "Elsewhere" presumably means a window closed somewhere other than where its card's work ends, such as a secondary dialog closed mid-card. Spell that out, for example: "close a window other than at the end of its card's work".

2. skills/uipath-genome/references/source-migration-guide.md:41,49

OK

  • Label row: Do While (InterruptibleDoWhile, already in package-doc-errata-guide.md:24) is the right target. The three named anti-shapes (duplicated priming step, start-only counter, "has run" flag) are concrete and checkable.
  • New "Run code" row: it is placed logically after "Call another source process". The examples are bounded, and "code only for the part no activity does" keeps the remaining code limited to what no activity covers.

3. skills/uipath-rpa/references/xaml/common-pitfalls.md:489

Low

  • The addition is correct and consistent with uipath-rpa/SKILL.md:63 (NApplicationCard for opening apps).
  • Scoping. The PR edits two skills. The rule is generic and stands on its own, so this is fine; it is noted only because pr-review.md asks for skill-scoped changes.
  • No UIA coupling. The sentence adds no UIA-version-coupled CLI or step content.

Checks run

  • Links: all links in the changed lines resolve.
  • Flavors: there are no studioweb overrides for any of the three files and no skill-flavor markers in them, so there is no flavor drift.
  • Hygiene: no secrets, personal paths, frontmatter or CODEOWNERS impact.
  • Cross-skill: no new links between skills.

What's Missing

  • Anti-patterns list. ui-target-migration-guide.md:120 (anti-pattern 12) covers "Start Process then attach" but not the new attach-in-Try/Catch → launch → flag shape. Consider extending it: "...or attaching in a Try/Catch and launching on failure, with a flag recording which path ran". Agents follow the numbered anti-pattern list reliably.
  • Tests. No coder_eval task covers the new rules (the attach-or-open card, the priming-loop → Do While, the code → activity rows). This is not blocking for small reference edits. If a genome migration fixture exists, a file_contains / command_not_executed-style check would catch regressions: no InterruptibleDoWhile missing, no TryCatch wrapping an NApplicationCard attach.

Area Ratings

Area Status Notes
Frontmatter OK Untouched
E2E Tests OK No new skill; optional coverage noted above
Skill Body OK SKILL.md untouched
References & Assets OK Low: option naming, wording on line 38
Repo Hygiene OK Two skills touched; changes are related

Issues for Manual Review

  • Check that the Application Card's Open option, set to open only when no instance exists, really covers every source "is it running / is the window open / is the session attached" test. In particular, ByInstance vs window-level attach may differ when a second instance should be launched on purpose.
  • Check the Do While rule against sources where the pre-loop step is not quite the same as the body, for example a priming read with different arguments. The current wording ("no step is written twice to run once before the loop") applies only to identical steps; a different priming step should stay as written.

Conclusion

Approve with minor suggestions. The rules are correct and tightly worded, and they close real over-translation patterns. The optional follow-ups are the enum and property names, the "elsewhere" wording, and an anti-pattern entry for the Try/Catch attach.

@vlad-coteanu-uipath
vlad-coteanu-uipath force-pushed the genome/app-card-lifecycle-loop-tests-code-steps branch from 2900c9f to ca7a3b4 Compare November 15, 2026 15:57
@vlad-coteanu-uipath vlad-coteanu-uipath changed the title Open, attach and close an application through its card; test a loop where the source tests it; build code steps as activities Application card lifecycle with no handle across a library; loops, rethrow-only handlers and passed-down values worded by their result; code steps as activities Nov 15, 2026
…lues worded by their result; no application handle crosses a library call
@vlad-coteanu-uipath
vlad-coteanu-uipath force-pushed the genome/app-card-lifecycle-loop-tests-code-steps branch from ca7a3b4 to 7fafa7d Compare November 15, 2026 16:02
@vlad-coteanu-uipath vlad-coteanu-uipath changed the title Application card lifecycle with no handle across a library; loops, rethrow-only handlers and passed-down values worded by their result; code steps as activities Planner: loops, rethrow-only handlers and passed-down values worded by their result; no application handle across a library call Nov 15, 2026

@danmunteanu1 danmunteanu1 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Commented · 2 blockers · 2 non-blockers
The rethrow rule drops handling a broader catch depends on, and the handle rule contradicts uipath-rpa until #4551 merges.

What

  • Genome format: a loop that only computes, selects or tests is written as its result; a catch that only rethrows gets no Error Handling entry; a value passed down only to reach its reader is read by that reader.
  • Both copies of the attached-application rule (planner and builder § Interface): no application handle crosses a library call.

Overall findings

  • 🔴 Blocker · Merge order. On main, uipath-rpa references/library-authoring-guide.md rule 5 is "Return application handles": a public workflow outputs the window or browser, and downstream workflows take it as an input. Merged alone, this PR has the genome and the builder's reading guide say the opposite, and a library build reads both. Fix: merge with #4551 or after it, and say so under Related PRs.

Outside this PR

  • "Run skill smoke tests" is red: skill-planner-genome-from-sdd scored 0.60 (16/17 tasks, under the 95% gate) because the run wrote a process genome where the task expects a component genome. The same task fails with the same checker output on #4692 and #4740, which do not carry this diff.

Behaviour: the same synthetic export was extracted with the base and with this PR merged with #4559 and #4551 (one run per side, same model). On this tree the genome writes the three loops as their results, gives the rethrow-only handler no Error Handling entry, has the submitting step read the machine name itself, and its library passes no browser handle. On the base the loops are per row, the handler is "caught and rethrown unchanged", the machine name is an input of three steps, and a Browser handle argument crosses every library call. The counter-case in the blocker below wasn't in the export.

tl;dr Keep the rethrow-only catch ahead of a broader catch as an entry, and merge with #4551; the other two are wording.

### Error Handling
Same step-associated layout as Business Rules, plus `### Global`. Behavioural wording: "Retries 3× on timeout, then routes the item to the exception queue" — never "RetryScope with NumberOfRetries=3". An entry states the failure, the outcome and the level that handles it; a failure that every UI step shares ("expected element not found: screenshot, stop naming the step") is written once under `### Global`, not repeated per step, and a step entry exists only where that step's handling differs. A Workflow substep's "confirm …" is a post-condition of the action before it, not a separate check (execution builds it as that action's verification).

**A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Blocker · A rethrow-only catch ahead of a broader catch is handling: it keeps that failure from the broader handler.

Try raises a business-rule exception; Catch BusinessRuleException → Rethrow; Catch Exception → log and retry. Without the first catch the second one catches the failure and retries it; with it, the failure goes to the caller unretried. Run on System.Activities TryCatch: with only the general catch, its handler ran; with a rethrow-only ArgumentException catch ahead of it, the ArgumentException escaped to the caller. Under this rule the genome writes no entry for that catch, and the build retries business-rule failures.

Fix:

Suggested change
**A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does.
**A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A rethrow-only catch ahead of a broader catch of the same block that does handle is the exception: it keeps that failure from the broader handling, and its entry says so ("a business-rule failure is not retried"). A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does.

**Library components** (a project other components consume as a package) carry, instead of the three bullets, one table per public workflow — never one table shared by several, which hides each workflow's types and directions: `Argument | Direction | Type | Description`. The Type is the one the rebuild gives the argument — a flag is a Boolean and a count a number, whatever text the source carried them in — and the description states the default and the value format (what a flag means, how a date is rendered, which side quotes a value), plus the conventions consumers rely on (naming, defaults, what a failed final check does). This table is the contract consumers are authored against before the library packs; every detail it omits becomes a question between two build groups. A workflow over the analyzer's argument cap (20) carries its optional switches and values in one options object — one In argument with its own table (`Field | Type | Default | Description`).

**State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, an attached application or handle, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application crosses as the application handle the owning skill's public-workflow contract has workflows return and accept. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions).
**State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: a library hands no application handle out for a caller to pass to another call, and each activity gets the application through its own Use Application/Browser card where it uses it. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔸 Non-blocker · How a workflow gets its application is uipath-rpa's public-workflow contract, which #4551 words as this line does ("each activity gets the application through its own Use Application/Browser card"). Here it reads as one card per activity. Name the contract, as the base line did, and keep what the genome writes: no handle argument.

Fix: (the builder copy, genome-reading-guide.md:52, changes with it)

Suggested change
**State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: a library hands no application handle out for a caller to pass to another call, and each activity gets the application through its own Use Application/Browser card where it uses it. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions).
**State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: the owning skill's public-workflow contract has each workflow open or attach to the application itself, so no argument carries a window or browser handle. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions).

**Library components** carry one table per public workflow, `Argument | Direction | Type | Description`: the type the rebuild gives the argument, its default and value format, and the conventions consumers rely on. Consumers are written against this table before the library packs. A workflow over the analyzer's argument cap (20) takes its optional switches and values in one options object — one In argument with its own table (`Field | Type | Default | Description`).

**State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, an attached application, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses as the application handle the owning skill's public-workflow contract has workflows return and accept. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller.
**State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: a library hands no application handle out, and each activity gets the application through its own Use Application/Browser card where it uses it. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔸 Non-blocker · Same change as the planner copy (genome-format-guide.md:75): the two copies change together.

Fix:

Suggested change
**State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: a library hands no application handle out, and each activity gets the application through its own Use Application/Browser card where it uses it. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller.
**State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: the owning skill's public-workflow contract has each workflow open or attach to the application itself, so no argument carries a window or browser handle. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller.


**A source's workaround for its own platform is not behaviour.** A clipboard copy between two ranges, a temporary file written beside the input, a rename around a path the source's script cannot open, a user setting switched to steer a file format: the step states the result the workaround produced, and the Source Map names the workaround — unless a later step reads what it leaves behind, which makes it data.

**A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔸 Non-blocker · None of the three forms fits a loop that adds each row's amount to a total or counts rows, a common computing loop.

Fix:

Suggested change
**A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step.
**A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, adds each row's value to a total or count, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the total of {field} over the rows where …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants