CLAUDE.md@skills/uipath-genome git:20261020.76627ddA

Immutable. This exact content never changes and is served at /api/v1/blob/508a3694e192eb5b.

# uipath-genome — Subject Homes

Every subject is stated in full in exactly one file; every other mention is a one-line pointer to that file and section. Edit the home; leave the pointers. A change touching more than the home plus its pointers is putting content in the wrong file.

## Home per subject

| Subject | Home |
|---|---|
| Genome levels (component / process), test-components-are-one-test-project exception, section rules, stubs, population matrix, `*[Inferred]*`, write-then-offer-edits, complexity inference | `references/genome-format-guide.md` |
| Composite UI interaction **contract** (what a substep must carry) | `genome-format-guide.md` § Workflow |
| Credential asset per login account; secrets never in genome, data file or report | `genome-format-guide.md` § Platform Dependencies; at build: `execution-guide.md` § 2.2, credentials |
| Source Map contract rows and the step table (its columns and rules); "genome files are the only output" (locators and rows stay in export) | `references/extracted-genome-guide.md` § Source Map |
| The kinds of source fact read from the source, never from its rendering (literals and case rules, counts, lengths, waits and budgets, set or typed, control-flow flags, formats, built-ins, parameter documentation, log texts) | `extracted-genome-guide.md` § Source values |
| The source-defect marker, the evident intent, which behaviour the rebuild follows, user rulings, the defect index | `extracted-genome-guide.md` § Source Defects |
| What `scripts/check-genome.py` checks (its docstring), which the genome tasks also grade with; when each mode runs it | the script; the extraction guide Step 6b, the authoring guide Step 8, the editing guide § Check after every edit, the source-migration guide § Migration preflight |
| Transactional Shape: the unit-of-work test and its granularity (alternative unit of work), flows versus nested levels (the two tests of rule 12), producer and consumer roles and the Type-cell role word, queue-vs-direct choice, the three outcomes and the conditional Postponed row, step groups, two-level sources folded into one unit of work, configuration split, traceability, one Recommendation verdict, stub | `references/transactional-shape-guide.md` |
| Extraction pipeline, related-resources question, sizing and the reading plan, evidence policy for blanket screen captures, completing and checking Source Map | `references/extraction-guide.md` |
| Verifying a suspected source defect: the two passes, the classification table, vendor-settled semantics, verdicts from subagents, writing while verdicts are out | `references/defect-verification-guide.md` |
| Authoring steps, scenario proposals for a goal, platform-capability suggestions, bounded follow-ups | `references/authoring-guide.md` |
| Edit requests and what each updates, for any genome and for extracted genomes; the check after every edit; partial re-extraction | `references/editing-guide.md` |
| Build With skill names, decision tree, operate-only skills, common combinations by shape | `references/skill-mapping-guide.md` |
| Configuration and scaffolding questions (the subagent model and parallel-parts question and the source-fidelity question among them), project/solution resolution, library gating, skill groups, owning-skill contract, acceptance verdicts, completion report and its split line | `references/execution-guide.md` |
| Applying or declining the transactional shape at build: split questions and their answer line, autonomous split defaults, projects a split materialises, REFramework template creation, groups and surfaces, the REFramework build items, alternative unit of work, four-exit verification | `references/transactional-execution-guide.md` |
| Work in parts in either mode: the orchestrator, shared decisions before fan-out, the brief and its rulings, a ledger per part with its Resume block, resuming, per-part read plans, forks (when, fork or fresh subagent, what a fork does, review), returns as verdicts checked against the disk, one owner per shared artifact | `references/parts-guide.md` |
| What extraction's parts add: one part per component, who writes, the shared-decision list, the extraction fork's shared reads, the part's read plan, own defect verification, the return contract, reconciliation | `references/extraction-parts-guide.md` |
| What a build's parts add: the project owner and its shared operations, the project ledger contract and progress file, planning parts, per-activity discovery in the read plan, one host per project, linking order, solution mutations, the run brief's contents, the part report and its mechanical checks | `references/execution-parts-guide.md` |
| Open-items files: target-environment setup steps for the engineer (per project and per solution) | `references/open-items-guide.md` |
| Migration preflight (including the secret scrub and what the build follows when the genome and the source disagree), credentials from the source's accounts, what each **kind** of source step becomes at build time, the source's names and shape kept in the rebuild and the correspondence table, executor records | `references/source-migration-guide.md` |
| UI target migration: the migrated-target rules, the target spec, link ordering and idempotency, Object Repository identity, composite **patterns** (build), Element Scope, the three verification verdicts per family | `references/ui-target-migration-guide.md` |
| Where a UI check goes in every build (`VerifyOptions` on the acting activity, a Check activity only for a branch, a test project's checkpoints), failure handling and logging once | `references/ui-verification-guide.md` |
| Test components at build: test-case shape, the test-data rules and pipeline (store → entity, files → variations), result parity | `references/test-execution-guide.md` |
| Every technology-neutral UiPath-side selector fact: tag chain per technology, attribute tiers and roles, `wnd`, matching semantics, rules 1–16 (criteria, purpose, `aaname`, captions and `<nav>` paths, position, tables, scope, identifiers, description, confidence, no-selector, one tag one node, driver verification, widget roles), § Checking a definition | `references/selector-translation-guide.md` |
| A technology's tags and its part of rules 4–16: web (`html`, `webctrl`, the `aaname` test, web grids and scopes, web widget anatomy) | `references/selector-translation-web-guide.md` |
| SAP GUI (`wnd` session attributes, `sap`, SAP tables and session windows) | `references/selector-translation-sap-guide.md` |
| Desktop (`uia`, `ctrl`, `java`, other tags) | `references/selector-translation-desktop-guide.md` |
| Definition shapes when no application reachable; the workaround for a number attribute bound to a selector variable, reachable or not (temporary: the file is deleted once the UIA CLI creates a first definition offline and registers a number attribute bound to a selector variable) | `references/offline-definition-workarounds-guide.md` |
| Corrections to an installed package's per-activity docs until the corrected package ships, and tool defects met in builds with what the build does instead, until fixed (temporary: a package's section is deleted once that package's shipped docs carry the corrected text, a tool's row once the tool behaves as its docs say, the file once no section is left) | `references/package-doc-errata-guide.md` |
| UiPath source facts: reading order and designer-noise filter with the connector schema caches and the compressed connector configuration (no inventory script), detection, inventory, signals per artifact type (project settings, test projects), platform resources, the deployed state (processes, versions, binding overrides, connection identities, triggers, job history, the other processes sharing its resources) and its Source Map rows, provenance, pitfalls, which REFramework file feeds which Transactional Shape row | `references/uipath-source-guide.md` — the reference implementation of a source guide, with the sections the pack's `CONTRACT.md` gives every source guide |
| A refactor (executing a genome extracted from a UiPath source, or from another framework when the request asks for one): the contract (kept, changed with a reason, carried over), the refactor questions (retire, fold, target, rulings on source defects, run modes, run record, connections) and their answer line, choosing the target (steps typed by the mapping guide's decision tree, one host, coordination replaced by the target's means, capabilities confirmed without a tenant, shape-deciding probes), the refactor plan, characterization tests, shadow and write-test modes and the comparison, the Cutover section of the open items, done and its report line | `references/refactor-guide.md` |
| What a framework pack must contain | `CONTRACT.md` in the framework migration pack — ask the user for its location |
| Framework facts only: detection, inventory, signals, composite-action wording, locator formats, per-field translation tables, framework pitfalls, inventory scripts, worked examples | `<PACK_DIR>/<framework>/source-guide.md`, `selectors-guide.md`, `scripts/`, `examples/` in the framework migration pack — never in this skill |
| Mode detection and the boundaries with sibling skills (planner, activity-migrator), framework pack resolution (ask for location, select row, run then read), one- or two-sentence rules naming subject and home | `SKILL.md` |
| What each mode reads at each phase and the condition that opens each guide, the three-turn reading rule | `SKILL.md` § Read Plans |

## Rules

1. **Generic first, framework second, never application-only.** A rule that holds for any source lives in a generic guide; a source guide keeps only what is specific to its framework and points to the generic rule. Application material (Workday, SAP, …) survives only as a worked example inside the generic rule it illustrates, and only when it shows what the generic wording cannot, or in that framework's guides. Values from the run that prompted an edit (hosts, project and asset names, counts) are not examples.
2. **A procedure lives in the guide of the mode that runs it.** Extraction-time steps in the extraction guide, execution-time steps in the execution or migration guide, even when both run the same script.
3. **SKILL.md is a router.** A Critical Rule names the subject and its home in one or two sentences; it never restates conditions, numbers or examples. Anti-patterns in SKILL.md route; the prohibition in full lives with the subject.
4. **Anti-pattern lists hold only the file's own subjects.** Everything else is a pointer, or is deleted when the home already states the prohibition.
5. **A pointer may add detail only when that detail exists nowhere else.** Prefer adding it to the home.
6. **Catalog files are read by section, rule files in full.** The per-technology tables in a framework selectors guide are a catalog: list headings, read the sections for the technologies in play. The UiPath side's tags live in one selector guide per technology, each read whole when its technology is in play. Rules, procedures and contracts are read whole. Say which kind a file is at its top.
7. **Keep the external contracts** unchanged unless the change is the point: frontmatter `description`, the pack resolution steps and the pack's README § Frameworks table shape, the Source Map contract rows, script names and flags.
8. **No meta-commentary.** Do not write sentences about the document's own editorial behaviour or reconcile differences between files in prose; if two files disagree, fix one.
9. **What another skill, a CLI or an activity package's docs own is named, never restated.** A file layout, schema, field or type list owned by another skill or a CLI changes with that owner, and so do an activity's settings, modes and limits, which its package doc owns. Name the artefact or capability (the REFramework template's configuration file, the shape the entity-create command accepts, the driver default) and let the build read the details from the owner. UIA CLI syntax is the strictest case: `uip rpa uia` subcommands, their flags and artifact filenames are co-versioned with `UiPath.UIAutomation.Activities` and drift. Name the capability (driver default, attribute listing, selector evaluator, snapshot reload, the OR CLI's listing / replace / create commands, element-interaction probes) and route syntax to the package guide `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md` § Documentation. The vocabulary is defined once in selector-translation-guide rule 15. Generic `uip rpa` commands (`validate`, `activities get-default-xaml`, …) are stable and allowed. `offline-definition-workarounds-guide.md` is the labelled temporary exception.
10. **Conflicts resolve toward the most recently verified statement** (a live driver pass beats a first-pass inference beats a vendor document), and the resolution is recorded in the PR.
11. **Name the subject, not the step.** Refer to another part of a procedure by what it is — "once every verdict on a suspected source defect is edited in", not "once every Step 4b verdict is edited in" — so the reader need not look the step up. Keep a step number only in a pointer the reader follows to that section.
12. **UiPath behaviour is written as the latest version shows it.** The newest package source and prerelease and the current CLI are the ground truth, with no per-version conditions; a rule that holds on every version carries the older versions' safety. `package-doc-errata-guide.md` is the labelled temporary exception: it bridges released packages until their corrected docs ship.
13. **The skill ships no selector checker and no target tool.** A structural selector check proves shape, not that anything matches the screen, and a maintained rule set drifts from the selector guide; the registration and linking commands follow the installed UI Automation package (rule 9). A run writes its own script where it needs one, as selector-translation-guide § Checking a definition and source-migration-guide § UI targets state.

14. **A file's boundary is its audience: mode × condition.** A rule sits in the file every session that needs it reads, and in no file a session reads without needing it. A file every session of a mode reads holds no conditional block above about 5 KB; a block under about 5 KB whose condition is common stays where it is.
15. **Every reference file has its row in SKILL.md § Read Plans,** keyed by a condition decidable at that phase, written in the same change as the file. Reads are named by the plan, never discovered by following pointers; a pointer into a section of a file the plan did not open is a section read.
16. **The framework migration pack cites this skill's rules by their subject**, in the skill's own words — a section heading or a bold rule head ("the skill's rule that one tag is one node", "the skill's Source Map contract") — never by file name or number, so files here move, split and renumber without touching the pack. Renaming a subject the pack quotes updates the pack in a paired pack PR.
17. **Check each added sentence against what its reader reads in that mode** (SKILL.md § Read Plans and § Source Frameworks), and cut it when those reads already give it. At Execute the pack's source guide is read only in the sections the skill points to, so a pack fact a build needs reaches it through one pointer in a file the build reads. What the owning skill's routing already opens for the work being built needs no pointer. A step that says where its output goes is not listed again among the run brief's contents or a read plan's reads.

## Where to put new content

| New content | Home |
|---|---|
| UiPath selector fact (new attribute, tier, matching quirk, node rule) | the selector guide of its technology — a new driver tag or attribute family with its tier source (package reference, or *derived*); selector-translation-guide when it holds for every technology — then reference from framework guide |
| New build pattern for a composite interaction that holds across technologies | ui-target-migration-guide § Composite interactions (+ source guide's wording row) |
| A rule for where a UI check goes, in any build | ui-verification-guide |
| A rule for building test components or migrating their data | test-execution-guide |
| A build or selector fact for one technology (SAP GUI tables, a Java grid) | that technology's selector guide, read only when the technology is in play; a pointer where a package doc owns the detail |
| Framework's new action, locator format or pitfall | that framework's source or selectors guide |
| New genome section or content rule | genome-format-guide (+ templates); a Transactional Shape rule: transactional-shape-guide; a Source Map, source-value or source-defect rule: extracted-genome-guide |
| New edit request or a rule for edits | editing-guide |
| A rule for verifying suspected source defects | defect-verification-guide |
| A rule for parts, subagents, forks or resuming that holds in both modes | parts-guide; what one mode adds: extraction-parts-guide or execution-parts-guide |
| New scaffolding question or report line | execution-guide |
| A rule for rebuilding a UiPath automation — what a refactor keeps, asks, plans, tests, builds for verification or hands over for the cutover | refactor-guide; a fact about reading a UiPath source or its deployed state: uipath-source-guide |
| A framework's transactional construct (queue, work list, per-item loop, framework template) | UiPath: uipath-source-guide § Signals — XAML › REFramework projects; any other framework: its source guide in the framework migration pack, pointing to genome-format-guide § Transactional Shape — nothing in this skill |
| New framework | A `<framework>/` pack in the framework migration pack (source guide, selectors guide, script, example, smoke task) plus its row in its README § Frameworks — in one change there; nothing in this skill |