Skip to content

docs: restore the guide to working with UiPath genomes - #4651

Merged
danmunteanu1 merged 3 commits into
mainfrom
docs/working-with-genomes-guide
Nov 12, 2026
Merged

danmunteanu1 merged 3 commits into
mainfrom
docs/working-with-genomes-guide

Conversation

@danmunteanu1

Copy link
Copy Markdown
Collaborator

What

  • Restores docs/guides/working-with-uipath-genome.md and its two diagrams, removed by Update CI, docs and repo scripts for the genome split (6/6) [PILOT-9071] #4379, brought in line with the split: uipath-planner writes every genome, uipath-genome builds it.
  • Restores the back-link from live-healing-pass.md; links the guide from the README's uipath-planner row.
  • CODEOWNERS: the guide gets the owners of live-healing-pass.md.

Changed against the removed version

  • Who does what: the planner writes and edits a genome, the genome skill builds; new row for a PDD (design: SDD first, then its genome).
  • Extraction: states its reading plan and continues; asks where the rebuild runs, and per part fold / product / retire before the genome is written.
  • Refactor questions: split between extraction and build.
  • Build: questions include the split and the live application; verdict met (static); hand-off folder <name>-handoff/ with README.md, open-items.md, live-checks/; UI target labels offline-unverified and verified.
  • Step 4: the live check and the runs follow the build's two answers (reachable application, healing pass), not separate requests after the build.
  • Tables: refactor products (queue items, a person's task, coordination), one Object Repository element per control, when shared behaviour becomes a library, Source Map rows for what is not rebuilt, the Data Fabric exception to "stays on this machine".
  • who-does-what.svg: labels of steps 3 and 4.

Added

  • A genome as written: a step, a source defect and an acceptance criterion, quoted from one run's genome.
  • What a run looks like: a small run (one process of 458 steps; 17 minutes to a genome, 78 to three projects that validate and build, nothing run) beside the large one. The large run's table drops its activity, code and helper-script counts.
  • Opening: what each skill and the uip command line do, and the three things left to people.
  • Before you start: what to bring, the process document first.
  • Build: a source defect comes back as a question; existing projects are reused; libraries as packages; large builds run in parts.
  • Live check: sign-in stays with the person; an application on another machine through the RPA skill's remote session; changes the runs made are listed in the report.

Verified

  • Every statement about the two skills read against skills/uipath-planner, skills/uipath-genome and .claude/rules/genome.md at 731f99b. Source only, no run.
  • node scripts/check-skill-links.mjs, node scripts/compose-skill-flavor.mjs validate, python scripts/check-skill-status.py pass. The link check does not cover docs/; the guide's four anchors were checked by hand.
  • who-does-what.svg rendered and read.
  • The small run's figures counted from its hand-off (README.md § Status), its genome files and its session logs. The remote session read in skills/uipath-rpa/references/remote-session-guide.md, not run.

Not verified

  • "How far it is proven" and the figures under "What one run produced": records of October runs, carried over unchanged.
  • Practical advice with no skill text behind it: the browser extension and an unlocked session for live runs, a VM or spare machine.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @danmunteanu1's task in 1m 32s —— View job


Summary

This PR restores docs/guides/working-with-uipath-genome.md and its two SVG diagrams, which #4379 removed. The guide is rewritten for the current split: uipath-planner writes the genome and uipath-genome builds it. The PR also adds the back-link from live-healing-pass.md, a README pointer and a CODEOWNERS entry. Only docs/ and repo-root files change; no skill files are touched.

Change-by-Change Review

1. docs/guides/working-with-uipath-genome.md

Severity: Low

I checked the guide's statements against the skills at HEAD. These all match:

Statement in the guide Where the skill says it
Hand-off folder <name>-handoff/ beside the project or solution, containing README.md, open-items.md, open-items/<project>.md and live-checks/ uipath-genome/references/completion-report-guide.md:6-12, open-items-guide.md:10
Labels offline-unverified and verified ui-target-migration-guide.md:91-105
Verdict "met (static)" completion-report-guide.md:90
Questions in batches of up to four configuration-questions-guide.md:60 (says "at most four")
"take the defaults" waives the questions turn configuration-questions-guide.md:68
A large build runs in parts, at most two at once, on a smaller model execution-parts-guide.md:13
The agent never types a password live-application-guide.md:7
Writes to a tenant need an answer that allows them; Data Fabric is the exception the build asks about execution-guide.md:210, configuration-questions-guide.md:31
Up to three rounds of questions for an idea author-guide.md:101 (complex: 2–3 rounds)

Other checks:

  • Anchors: #what-a-run-looks-like, #not-a-one-to-one-translation, #rebuilding-an-existing-automation and #4--check-run-and-fix all match GitHub's slugs for their headings.
  • Links: images/*.svg, live-healing-pass.md and commands/install-permissions.md all exist. The plugin name is uipath, so /uipath:install-permissions is correct.

Minor points (not blocking):

  • L140, ambiguous comparison. "The live-run loop comes from a smaller run (7 steps, three live runs)" now sits under the large-run heading, and a new "A small one" run of 458 steps appears just above it. "Smaller run" reads as if it means the 458-step run, when it is a third, separate run. Suggest wording such as "a separate 7-step run with three live runs".
  • L55, broken grammar. "when it is more than one or a few activities do" doesn't parse. Suggest "when its work is more than one or a few activities".
  • L61, hard to read. This paragraph packs four separate ideas into two sentences. Suggest splitting it.

2. docs/guides/live-healing-pass.md

OK. The back-link anchor #4--check-run-and-fix resolves.

3. README.md

OK. The guide link resolves. One check: the README catalog table may be regenerated by check-skill-status.py --write-readme. If that rewrites the Description column, it would drop this link. The PR says the script passes, so this is probably fine.

4. CODEOWNERS

OK. Same owners as live-healing-pass.md.

5. docs/guides/images/*.svg

OK. Both are text SVGs (not raster images), each with an aria-label. Light and dark styles both work. The step labels in who-does-what.svg match the guide's headings (step 4 is split into "Check and run" and "Fix loop").

What's Missing

Nothing identified.

Area Ratings

Area Status Notes
Frontmatter OK No skill files changed
E2E Tests OK Not applicable (docs only)
Skill Body OK Not applicable
References & Assets OK Links and anchors resolve; claims match the skills
Repo Hygiene OK CODEOWNERS updated; no secrets or personal paths; the SVGs are text

Issues for Manual Review

  • L217, remote session not routed from the genome skill. "the RPA skill can work on an Orchestrator unattended robot there through a remote session" is true of uipath-rpa/references/remote-session-guide.md. But nothing in uipath-genome's live-application or healing-pass guides sends a live check to that path. A reader may expect the genome build to offer it on its own. Consider adding "ask for it" or similar, or confirm the build reaches it through delegation.
  • Figures not re-checked here. The October-run figures and "How far it is proven" (L119, L136-153) are carried over, as the PR body says. The small run's figures (L123-132) can only be checked against the run artefacts.
  • Sensitive-content scan not run. I couldn't run scripts/check-sensitive-content.py here because the command needed approval. The dates in the guide are prose ("9 Nov 2026", "7–8 Oct 2026"), not the blocked MM/DD/YYYY shape, so the required check should still pass.

Conclusion

Approve. The guide matches the current planner and genome skills, and its links and anchors resolve. The remaining points are wording polish plus one routing question (L217) for the owners.

@danmunteanu1
danmunteanu1 merged commit e0360dc into main Nov 12, 2026
47 checks passed
@danmunteanu1
danmunteanu1 deleted the docs/working-with-genomes-guide branch November 12, 2026 14:57

@vlad-coteanu-uipath vlad-coteanu-uipath left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Checked every statement against skills/uipath-planner and skills/uipath-genome at main (source only, no run). Most hold; the inline comments are the ones that tell a reader something the build does not do, or contradict another line of the guide.


Before it builds, the agent asks whether it can reach the application, or a comparable test copy of it, and how far it may go there. The recommended answers are the cautious ones: not reachable, and a read-only check with no runs. [Live healing pass](live-healing-pass.md) lists what to tell it, what to ask before the first run, how to question a failure and what the final report must say.

**Prepare:** open the app in a test environment and sign in yourself, since the agent never types a password. Then keep off the mouse and keyboard: the agent takes over the screen, so a VM or a spare machine works best. When the application is only on another machine, ask for a remote session: the RPA skill then works on an Orchestrator unattended robot there. In your answer, name the window or URL it may use and what it must never close.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The build has no remote path. skills/uipath-genome/references/live-application-guide.md § Runs ends "The runs are the local runs the acceptance verdicts cite", and § Driving the application puts the window baseline and every capture on the local machine (items 2 and 5). The remote session exists only in uipath-rpa (references/remote-session-guide.md); nothing in uipath-genome routes a live check or a run to it. Asking for one at build is a request the build's own rule rules out. Drop the sentence until the genome skill routes its live phases to a remote session.

Suggested change
**Prepare:** open the app in a test environment and sign in yourself, since the agent never types a password. Then keep off the mouse and keyboard: the agent takes over the screen, so a VM or a spare machine works best. When the application is only on another machine, ask for a remote session: the RPA skill then works on an Orchestrator unattended robot there. In your answer, name the window or URL it may use and what it must never close.
**Prepare:** open the app in a test environment and sign in yourself, since the agent never types a password. Then keep off the mouse and keyboard: the agent takes over the screen, so a VM or a spare machine works best. In your answer, name the window or URL it may use and what it must never close.

- **What you have about the process.** A process document first (a PDD, an SOP, a runbook), then the automation itself, and any test evidence, recordings or tickets. The agent asks for them once and reads only what you give it.
- **Claude Code with the [UiPath skills](https://github.com/UiPath/skills).** Run `/uipath:install-permissions` once, so routine `uip` commands stop asking for approval.
- **For live runs:** the target apps installed and signed in on this machine, the UiPath browser extension, and the Windows session unlocked.
- **A test environment.** Live runs create real records. Everything else stays on this machine, with one exception the build asks about: Data Fabric entities the genome names are created in the connected tenant. Nothing is published or deployed unless you ask.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Under "take the defaults" (L165) the build does not ask this. skills/uipath-genome/references/configuration-questions-guide.md, autonomous-runs paragraph: a waived run takes every default, "the Data Fabric default included", and the Data Fabric row's Recommended option is "Create, and load where there are records". So the tenant write happens unasked. The same row also covers a record store a split answer keeps and test data kept in an entity, not only the entities the genome names.

Suggested change
- **A test environment.** Live runs create real records. Everything else stays on this machine, with one exception the build asks about: Data Fabric entities the genome names are created in the connected tenant. Nothing is published or deployed unless you ask.
- **A test environment.** Live runs create real records. Everything else stays on this machine, with one exception: Data Fabric entities the build needs (the genome's, a record store, test data) are created in the connected tenant and their records loaded. The build asks first, unless you say "take the defaults", which creates them. Nothing is published or deployed unless you ask.

e. Read the six values — Sleigh Registry library, Get Data
```

**A source defect** is written down where it acts, and kept as the source has it until you rule on it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Holds only when the intent is [Inferred]. skills/uipath-planner/references/shared/extracted-genome-guide.md § Source Defects: the rebuild follows the evident intent when the source states it (a comment or log text at the defect, a sibling copy that does it right); it keeps the source's behaviour until a ruling only when the step's purpose alone shows the intent. L63 and L195 state the first case, so this line contradicts them. The excerpt below is the [Inferred] case, so only the lead sentence changes.

Suggested change
**A source defect** is written down where it acts, and kept as the source has it until you rule on it.
**A source defect** is written down where it acts. The rebuild follows what the source says was meant; where only the step's purpose shows it, as here, the rebuild keeps the source's behaviour until you rule.

| Starts from the automation you have | Yes | Yes | No: specs the next change | Yes, or from an idea |
| A plain-language spec, reviewed before the build | No | No | Yes | Yes |
| Rules in error handlers, defaults and settings written down | Copied, not shown | Often lost | Not read | Yes, where they act |
| Built the target's way, not the old shape | No: same shape | Yes | Yes | Yes |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Contradicts L65 and the "as it is" options at L96–97: option 2 keeps the names and shape throughout (skills/uipath-genome/references/configuration-questions-guide.md, Source fidelity row: "the source's names and shape throughout").

Suggested change
| Built the target's way, not the old shape | No: same shape | Yes | Yes | Yes |
| Built the target's way, not the old shape | No: same shape | Yes | Yes | Yes, unless you choose to keep it |


Say "Build `<name>-genome.md`". The agent builds with `uipath-genome`, and asks its questions first, in batches of up to four, each with a recommended answer: the genome's open values, how to split work done item by item, the project location, XAML or C#, where settings live, package versions, and whether it can reach the application and how far it may go there ([step 4](#4--check-run-and-fix)). A rebuild as it is also asks how closely to follow the source; a refactor adds its own build questions ([Rebuilding an existing automation](#rebuilding-an-existing-automation)).

A source defect that needs your ruling comes back as a question, with where it is in the source and what it affects. The build also looks for projects that already exist, so a library built for an earlier process is reused instead of built twice, and asks whether each library becomes a package of its own.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Only in a refactor. skills/uipath-genome/references/configuration-questions-guide.md: rulings are a refactor question, asked when the Source Map names a UiPath source or the request asks to refactor. Otherwise skills/uipath-genome/references/genome-reading-guide.md § Source Defects: "An open ruling builds the option the genome names, marked [Inferred], until the user rules", and the completion report lists it under Rulings still owed.

Suggested change
A source defect that needs your ruling comes back as a question, with where it is in the source and what it affects. The build also looks for projects that already exist, so a library built for an earlier process is reused instead of built twice, and asks whether each library becomes a package of its own.
In a refactor, a source defect that needs your ruling comes back as a question, with where it is in the source and what it affects; otherwise the build follows the option the genome names and lists the ruling as still owed. The build also looks for projects that already exist, so a library built for an earlier process is reused instead of built twice, and asks whether each library becomes a package of its own.


A refactor is proven before the switch, with a way back:

1. **Questions**, in two places. Before the genome is written, per part: rebuild or retire it (retire only when its owner confirms nobody uses it), fold it into another when it only re-reads what that part already knew, and the product it runs on; the answers are in the genome you review. At the build, after the genome's own questions: a ruling on each source defect still open, whether to build a shadow mode and a write-test mode, how a run reports what it did, and which identity each connection signs in as.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Narrower in the skills, and L182 already words Retire correctly, so the two lines disagree. skills/uipath-planner/references/extract/extract-guide.md Step 6c: Retire is asked only for an entry point of a UiPath source with no run in the deployed-state window (Rebuild recommended); Fold also applies to a part started only by items that need no queue once the reads are batched, and to two parts on one schedule over the same data. skills/uipath-genome/references/refactor-guide.md: the Connections question is asked only for a connection the deployed state shows signed in as a person.

Suggested change
1. **Questions**, in two places. Before the genome is written, per part: rebuild or retire it (retire only when its owner confirms nobody uses it), fold it into another when it only re-reads what that part already knew, and the product it runs on; the answers are in the genome you review. At the build, after the genome's own questions: a ruling on each source defect still open, whether to build a shadow mode and a write-test mode, how a run reports what it did, and which identity each connection signs in as.
1. **Questions**, in two places. Before the genome is written, per part: the product it runs on; whether to fold it into another when it re-reads that part's output, needs no queue once its reads are batched, or shares its schedule and data; and, for an entry point of a UiPath project with no recent run, whether to rebuild or retire it (retire only when its owner confirms nobody uses it); the answers are in the genome you review. At the build, after the genome's own questions: a ruling on each source defect still open, whether to build a shadow mode and a write-test mode, how a run reports what it did, and which identity each connection signed in as a person uses.


## Before you start

- **What you have about the process.** A process document first (a PDD, an SOP, a runbook), then the automation itself, and any test evidence, recordings or tickets. The agent asks for them once and reads only what you give it.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

For an extraction this reverses the priority. skills/uipath-planner/references/extract/extract-guide.md § Related resources: "The source decides behaviour: a resource never adds, removes or changes a step, rule or value"; a document only settles what the source cannot show (purpose, actors, volumes, success criteria). "Reads only what you give it" is also short: for a UiPath source, extraction also reads the processes, triggers, bindings and job history of the Orchestrator folder you name.

Suggested change
- **What you have about the process.** A process document first (a PDD, an SOP, a runbook), then the automation itself, and any test evidence, recordings or tickets. The agent asks for them once and reads only what you give it.
- **What you have about the process.** The automation itself, or a process document (a PDD, an SOP, a runbook) when there is no automation yet, and any test evidence, recordings or tickets. The agent asks for them once and never searches for them. The automation decides what is built; a document settles what the automation cannot show.


## What a genome holds

A genome is a PDD and an SDD in one, written for the agent that builds it. When a solution design (SDD) was agreed first, the genome is written from that design and names it. A person reviews it, so it is in plain words, with no activity or variable names, and file names only in its Source Map. An agent builds from it, so every section is there for something the build does:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The planner keeps them apart: skills/uipath-planner/SKILL.md Critical Rule 4, a PDD "is never written — it is input only", and a PDD or process source gets "an SDD, then the genome of the agreed SDD". L180 says the same.

Suggested change
A genome is a PDD and an SDD in one, written for the agent that builds it. When a solution design (SDD) was agreed first, the genome is written from that design and names it. A person reviews it, so it is in plain words, with no activity or variable names, and file names only in its Source Map. An agent builds from it, so every section is there for something the build does:
A genome says what an automation does and how it is built, written for the agent that builds it. When a solution design (SDD) was agreed first, the genome is written from that design and names it. A person reviews it, so it is in plain words, with no activity or variable names, and file names only in its Source Map. An agent builds from it, so every section is there for something the build does:

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