# Extraction Guide — genome from an existing automation

Read source, then write a genome that reads as authored: behavioural, generalized, replication-grade, provenance confined to the Source Map. Content rules: [genome-format-guide.md](genome-format-guide.md). Framework specifics: source guide. Never ask the user what the automation does; artifacts tell you.

## Source Guides

A UiPath source is read with [uipath-source-guide.md](uipath-source-guide.md). Any other source is read through the framework migration pack: resolve it, select the framework row, run its script and read its source guide in full before Step 1, exactly as [SKILL.md § Source Frameworks](../SKILL.md) states. No pack, or no row matches → stop as that section says. Do not improvise an extraction from an unknown framework.

## Pipeline

### Step 1 — Detect

Run source guide's Detection table against the given path. Decide:
- **Framework** (which source guide).
- **Level:** the projects the rebuild needs decide it ([genome-format-guide.md § Two Levels](genome-format-guide.md)). A solution or multi-project bundle → process genome; a single project or workflow → component genome, unless the source guide's § Component Detection maps its parts to two or more projects.
- **Missing manifest:** proceed from artifact files; every value that would have come from the manifest is `*[Inferred]*`.

**Ask for related resources** once, with the pack question when that is asked: "Besides the automation, do you have other resources for this process (PDD, SOP, runbooks, test evidence, recordings, tickets)? Paths or links, or none." Skip it when the request names them or says none; when the request says to proceed without questions, ask it in Step 7 instead. Never search for resources the user did not give.

### Step 2 — Inventory

List every file per project, classify with source guide's Inventory table, drop everything in its Exclusions. Record artifact types present; read only those Signals sections of the source guide.

### Step 2b — Size the source and plan the reading

Measure what extraction will read before reading any of it. For a pack source, write the per-object renderings the source guide says to read (one bot's dump, one process's rendering) for every object into the working folder (a scratch folder outside the genome's folder, kept until edits are offered) with one command loop, and take their sizes; for a UiPath source, take the sizes of the files as read, after its designer-noise filter. Sum them per folder and per component candidate (source guide § Component Detection), list the largest objects, and count the entry points and test cases. Tokens are about bytes ÷ 4.

From these numbers choose the level, the components, and whether the reading runs in parts. **Parts are mandatory when the source to read exceeds one part's budget, about 400 KB (100K tokens).** A part reads its objects and its fixed reads (this guide, the format guide, the template, the source guide, the brief) and writes its output within one context: a compaction summary carries none of the source it read, and every turn resends the whole context, so cost grows faster than the reading.

State the plan in one message before the first object is read: level, components, the parts with their objects and bytes, the fixed reads every part repeats, the total read, that consumption is a multiple of that total because every turn resends the context, and — where the host lets the orchestrator choose — the model the parts run on and how many run at once. This is not a question about what the automation does. The message also names every object the source calls that the export does not hold, and asks once for its export: a callee is source, asked for and never searched for. One given later is read by [editing-guide.md § Partial Re-extraction](editing-guide.md); one never given is written as [genome-format-guide.md § Workflow](genome-format-guide.md) states for an automation the source does not hold. Then continue without waiting for a reply: the plan is the agent's own choice, stated so the user can redirect it, never put to them for confirmation. Parts: [extraction-parts-guide.md](extraction-parts-guide.md).

### Step 3 — Extract signals

Per artifact, in inventory order, using source guide's signal tables. Collect into working notes (not the genome) grouped by component:

| Signal class | Feeds |
|---|---|
| Steps and actions, with `DisplayName` or node labels | Workflow |
| Conditions, switches, loops, gateways, expressions | Business Rules, Workflow substeps |
| Try/catch, retry, error ports, boundary events, SLAs, escalations | Error Handling |
| Arguments, schemas, variables, data objects | Interface, Workflow data annotations |
| Applications, connectors, URLs, connection references | Target Applications |
| Invocation edges inside a component | Call graph → step order |
| Invocation edges across components, queues, tasks, events | Handoffs (process genome) |
| Triggers, schedules, entry points | Workflow step 1, Deployment |
| Queues, assets, credentials, buckets, connections, folders | Platform Dependencies |
| Per-item iteration with per-item outcomes: queue item fetch and status updates, a loop over rows or files with a per-item catch, a work-list read; framework state machines and their configuration workbook | **Transactional Shape** — unit of work and its alternatives, the As-is (produced by, consumed by, item store, coordination, item kinds, step groups), the outcomes, the split options derived with rule 8's table and the evidence ([transactional-shape-guide.md](transactional-shape-guide.md)); never a verdict; the framework's plumbing is not steps (source guide's framework section) |
| Hardcoded literals and configuration keys: paths, URLs, addresses, names, thresholds, columns | Configuration Questions for the open ones; every other one in the step, rule or handler that uses it ([genome-format-guide.md § Configuration Questions](genome-format-guide.md)) |
| Test cases, eval sets, assertions | Acceptance Criteria evidence |
| Prompts and instructions (agents) | Business Rules (paraphrased) |
| UI control recognition data (object maps, selectors, XPaths) | **Not written** ([extracted-genome-guide.md § Source Map](extracted-genome-guide.md)). Read source guide's target inventory (scratch folder) for each control's type and the actions applied to it — they decide substep wording; record counts in the Source Map. A selector a test asserts as a value (a generated, validated or matched selector compared with its expected text) is a comparison literal, not recognition data: written verbatim in its step |
| Composite UI actions (type-ahead picks, menu paths, option lists, find-row-then-act, keystrokes to the focused element) | Workflow substeps carrying the full interaction contract ([genome-format-guide.md § Workflow](genome-format-guide.md)); wording per source guide's § Composite actions |
| Data-driving rows (recordsets, data sheets) | **Not written.** Literals are placed like hardcoded ones (row above); row schemas feed Interface and test components' row tables; rows stay in the export |
| Login accounts used per scenario | Platform Dependencies: one credential asset per account ([genome-format-guide.md § Platform Dependencies](genome-format-guide.md)) |
| Screen capture steps | **Evidence policy**: counted in the Source Map, rebuilt at their positions (below) |
| Where everything came from | **Source Map** — the migration contract ([extracted-genome-guide.md § Source Map](extracted-genome-guide.md)) |

Read every relevant file. No sampling, no "the helpers are similar".

**Values are read, not inferred from their rendering.** Run the source guide's renderer self-test first when it has one. Every fact of the kinds [extracted-genome-guide.md § Source values](extracted-genome-guide.md) lists is written as the source states it. A fact the rendering does not show is read from the source object before it is written; a fact that cannot be read is flagged `*[Inferred]*` and named in the Source Map, never filled with a plausible number.

**Wrappers are not components.** A library that exists only to drive a technology through an identity passed to it — find the element by id, then click, type, read — is the source's substitute for a driver. Its calls are UI steps of the component that makes them, on the element the identity names; the identities are that component's UI targets (recorded in the Source Map's inventory with the recorder's captures), and the library's logon, session and certificate workflows are what remains of it as a component. The source guide's § Component Detection names such wrappers per framework.

**Related resources.** Read each resource from Step 1 after the source's signals. The source decides behaviour: a resource never adds, removes or changes a step, rule or value. It only settles what the source cannot show (purpose, actors, why a rule exists, volumes, success criteria), and a line it settles loses `*[Inferred]*`. List each resource in the Source Map's `Related resources` row with what it settled, or "not read" and why. Record every disagreement with the source in `Resource discrepancies`, never in the body.

**Evidence policy.** A source whose steps are dense with screen captures (settle-wait, full-desktop capture, next interaction) is recording its audit trail, not choosing verification points. The rebuild keeps every capture as a screenshot at its point, as it keeps log lines ([source-migration-guide.md § Source steps that are not UI actions](source-migration-guide.md)); never write one as a genome step — count them in each step's Captures cell of the Source Map's step table ([extracted-genome-guide.md § Source Map](extracted-genome-guide.md)). State the policy once per component, in Error Handling (in Error Handling and Recovery for a process genome, with the test-execution facts under Deployment): the source's density, that every capture is rebuilt where the source takes it and none is added, plus a screenshot on every failure. Give it an acceptance criterion: evidence not asserted is evidence nobody notices is missing. Read where the captures sit to say who owns the evidence (inside reusable sub-processes and none in the roots → library produces it, test cases collect it; in the roots → the opposite). Platform mapping: `uipath-test` owns execution evidence (screenshots and attachments per test case in Test Manager); the robot's own screenshot-on-failure covers the failure half; both belong under Platform Dependencies / Deployment, never in Build With. Log lines on almost every step are the same audit trail in text: state their density in the same place, that the rebuild logs where the source logged and adds its own logs only at business milestones and decisions ([source-migration-guide.md § Source steps that are not UI actions](source-migration-guide.md)), and that the rebuild keeps writing the source's log file, with the readers the export shows (a mail that attaches it, a step that parses it). Add a Configuration Question offering the job's log in Orchestrator instead (constant; default: the file, as the source writes it) — the export cannot show readers outside it, so dropping the file is the user's decision. Which step kinds count as checkpoints for the Source Map: source guide's § Evidence.

### Step 4 — Build graphs

- **Call graph per component** with source guide's Call Graph Rules → ordered workflow steps. An invocation made from a result or error route (run this process when the step fails) is an edge too, a conditional one; objects named alike are separate nodes — every edge names its callee by id, a step is described from the copy its caller runs, and two live copies are both carried. Dead code goes to the Source Map — but a branch is dead only when the conditions on every path to it contradict it for every value; prove that from the condition text before writing "dead" (an inner `contains X` under an outer `is empty OR contains X` is reachable for every value the outer condition admits). A wrong dead-code row drops behaviour from the build, and execution never edits the genome to restore it.
- **Handoff graph across components** from cross-component edges → Components order and Handoffs table. Each edge records mechanism, data passed, and failure behaviour visible in the source (error port, retry, boundary event, dead-letter queue). Every edge — or intra-component phase boundary — that hands items one by one (a queue, a file drop, a work table, a mailbox, a work-list file) is a **candidate flow** of the Transactional Shape: it starts a flow of its own only when its items are independent of the upstream item and the phases are separated; a store the same job fills and empties with each upstream item's own children (a mail's attachments, a report's work list and its rows) is a level of one unit of work, not a second flow; a component that takes items of one flow and creates independent items of the next is a chain ([transactional-shape-guide.md](transactional-shape-guide.md) rules 11–13).

### Step 4b — Verify every suspected source defect

A finding that the source misbehaves is a suspected defect until two passes settle it — the full rendering, then the framework's source itself — and it is written by its classification: [defect-verification-guide.md](defect-verification-guide.md).

### Step 5 — Infer complexity (component)

| Signal | Simple | Medium | Complex |
|---|---|---|---|
| Workflow files or nodes carrying logic | 1-3 | 4-8 | 9+ |
| Distinct target applications or connectors | 1-2 | 3-4 | 5+ |
| Entry points or triggers | 1 | 1-2 | 3+ |
| Conditional branches (if / switch / gateway / decision) | 0-3 | 4-10 | 11+ |
| Error-handling constructs | 0-1 | 2-3 | 4+ |
| Composite UI interactions carrying a contract (type-ahead pick, custom option list, segmented or picker date, menu path, row-by-content, dialog answer) | 0-1 | 2-4 | 5+ |
| Test cases of a test component, or checkpoints they assert (take the higher) | 1-3 cases / ≤6 checkpoints | 4-8 / 7-20 | 9+ / 21+ |
| Platform resources (queues, assets, buckets, connections) | 0 | 1-2 | 3+ |
| Human-in-the-loop waits | 0 | 0 | 1+ |

A **test component** is rated by its test cases and the checkpoints they assert; a **library** by its public workflows, counted as its workflow files, with the library as one entry point. Neither takes the population matrix's step minimums ([genome-format-guide.md § Population Matrix](genome-format-guide.md)).

Count only the rows that apply to the component: the composite UI row is left out for a component that drives no UI, the test row for one that is not a test component. Take the level most counted rows land on; ties go lower. Process genomes: [genome-format-guide.md § Complexity](genome-format-guide.md).

### Step 6 — Map signals to sections

Write the **process genome first** (when applicable), then each **component genome**.

| Section | From |
|---|---|
| Overview | Purpose synthesised from names, targets, data flow. Author's voice. Inferred intent gets `*[Inferred]*`. |
| Target Applications / Actors and Systems | Resolved applications (source guide § Target Resolution). Human lanes, escalation recipients, task assignees become actors. |
| Build With / Components | Source guide § Component Detection → skill per component; [skill-mapping-guide.md](skill-mapping-guide.md) decision tree for steps inside a hybrid component. Test components: one test project, typed and laid out per [genome-format-guide.md § Build With / Components](genome-format-guide.md). |
| Platform Dependencies | Source guide § Platform Resources. Keep source resource name. Credential asset per login account ([genome-format-guide.md § Platform Dependencies](genome-format-guide.md)). |
| Interface | Arguments, schemas, entry points. Must agree with the Handoffs rows touching this component. |
| Configuration Questions | Open values only: `N. {Question}? ({setting | constant}; default: {source value})`; every fixed value in the section where it acts ([genome-format-guide.md § Configuration Questions](genome-format-guide.md)). |
| Workflow / Process Map | Ordered from call graph; substeps for every multi-field, conditional, or transforming step; `(input: …; output: …)` annotations. |
| Business Rules | Conditions translated per format guide, attached to their step. Agent prompts paraphrased into rules. |
| Error Handling | Constructs translated to behaviour, attached to their step; `### Global` for global handlers. The business/system classification of per-item outcomes goes to the Transactional Shape. |
| Transactional Shape | Source guide's transactional signals, written per [transactional-shape-guide.md](transactional-shape-guide.md) rules 8, 10 and 11: the As-is exactly as the source has it (its queues, statuses, tags, locks, ledgers, parent and child levels, robot count), the split options derived from the signals for the unit of work and for each alternative unit, with what each requires and changes, the evidence as facts; candidates carry `*[Inferred]*`; no unit of work → the stub; no verdict, no role word in Components; framework files go to the Source Map as a `Framework files` row. |
| Handoffs | One row per cross-component edge from Step 4. |
| Acceptance Criteria | One per step, per transformation, per rule, per handler, plus edge cases. Existing test cases and eval sets become criteria directly (behavioural wording). |
| Deployment | Solution vs independent packages, triggers, folders from manifest and bindings. Count buildable projects: non-test components plus exactly one test project when test components exist. |
| Complexity, Tags | Step 5; applications + domain + platform features. |
| Source Map | The step table: per Workflow step its source objects, data sets and captures ([extracted-genome-guide.md § Source Map](extracted-genome-guide.md)); component → project in a process genome. Dead code, unresolved references, inferred steps, every suspected-defect finding with its classification and one Verification row per component ([defect-verification-guide.md](defect-verification-guide.md)). Plus migration-contract rows of Step 6b. |

### Step 6b — Complete the Source Map as the migration contract

Fill every row [extracted-genome-guide.md § Source Map](extracted-genome-guide.md) lists: framework, export root path and identity, the step table of every component genome (each step's source objects, the data sets its own objects read, its captures), checkpoints per step of a test component and of every library step a test component calls (source guide's § Evidence says which step kinds count), inventory counts. The call graph of Step 4 gives the source objects; a caller, and a callee that is a step of its own, go to the step's Notes. Nothing is written beside the genome.

Check the genome before offering edits. Run the source guide's inventory into a scratch folder **outside the genome's folder** (a temp directory, or one deleted after the check), then:

```bash
python3 "<SKILL_DIR>/scripts/check-genome.py" <process|component> "<GENOME_MD>" --profile strict --processes "<PROCESS_INVENTORY>" --recordsets "<RECORDSET_LIST>"
```

Use `python` on Windows. Pass the process genome, which takes the checker to every component genome through the Components table, or a standalone component genome. It checks the format rules, and each step table against the export: every source object and data set resolves to an object of that name, every Workflow step has exactly one row, and a library step built from a copy the built roots do not reach is flagged. It prints one `FAIL` line per miss and exits 1 while one remains. Fix every miss and run it again, at most three rounds; what is left after the third is named when edits are offered (Step 7). Execution runs the same check at preflight and meets every gap left.

A UiPath source has no inventory script: run the check without `--processes` and `--recordsets`, then check with Glob against the project that every step table's workflow path resolves, and that every entry point, public workflow of a library or registered test case has its row or is named in the `Not covered` row, identified as [uipath-source-guide.md § Provenance](uipath-source-guide.md) states. Fix every row that fails.

Before writing Configuration Questions, sort every literal and configuration key in the working notes as open or fixed per [genome-format-guide.md § Configuration Questions](genome-format-guide.md). An open value becomes a question; a fixed value is written in the step, rule or handler that uses it. A question that only its default can answer is a fixed value.

### Step 7 — Write and offer edits

Write all files, each named by the slug rule ([genome-format-guide.md § File Naming and Location](genome-format-guide.md)), then, once every verdict on a suspected source defect is edited in and Step 6b's check has run, ask "Want to adjust anything?" ([genome-format-guide.md § Write, Then Offer Edits](genome-format-guide.md)). With it, name every source defect whose rebuild behaviour is the user's to rule on, and every detail left open by an intent the rebuild must follow ([extracted-genome-guide.md § Source Defects](extracted-genome-guide.md)); a ruling given is written in as that section says. When the Source Map has a `Not covered` row, name its objects too: a build of the genome leaves them out unless they are translated now. Edits: [editing-guide.md](editing-guide.md).

## Anti-patterns

1. **Asking what the automation does.** Read it.
2. **Transcribing an open value, or asking a fixed one.** Queue name or path in the body instead of a Configuration Question with that value as default; the mirror, a posted value, limit, wait or count the source fixes asked as a question only its default can answer ([genome-format-guide.md § Configuration Questions](genome-format-guide.md)).
3. **Code in the body:** activity names, node types, variable names, file names, selectors, expressions. Translate; provenance goes to the Source Map.
4. **Integration Service as an application.** Resolve the connector to the vendor system.
5. **Flattening a solution into one component genome**, losing handoffs between projects, or emitting one test project per business area ([genome-format-guide.md § Two Levels](genome-format-guide.md)).
6. **Treating designer metadata, generated files, or test projects as workflow logic.**
7. **Sampling files.** Every non-generated artifact is read.
8. **Leaving a section empty because the source is ambiguous.** Write the best interpretation, flag it, note it in the Source Map.
9. **Extracting the behaviour and losing the provenance** — Source Map without the export's location or without per-step source objects — or its mirror, copies of the export's catalogs beside the genome (Step 6b; [extracted-genome-guide.md § Source Map](extracted-genome-guide.md)).
10. **Flattening a composite action to its data** — "Enter Voluntary into Primary Reason" for a type-ahead pick, "choose Terminate Employee" for a two-level menu path, "select row 2" for a row found by content ([genome-format-guide.md § Workflow](genome-format-guide.md)).
11. **Transcribing blanket screen captures as steps, dropping them, or keeping only the checkpoints'.** They are the evidence policy (Step 3). A genome that mentions screenshots only in an unhandled-exception handler has dropped the suite's whole audit trail.
12. **Transcribing framework plumbing as steps** — state transitions, retry counters, status updates, screenshots on exception — or dropping the framework's configuration workbook instead of carrying each row as a Configuration Question, a fixed value where it acts, or — a row of its assets sheet — the Platform Dependency that row names; the workbook itself is none ([transactional-shape-guide.md](transactional-shape-guide.md) rule 10).
13. **Asserting a split, a store or a verdict in the Transactional Shape** — a `Recommendation` line, a role word in the Components Type cell, a Consumer row that names a mode, or a split option presented as the design — instead of the As-is, the options and the evidence ([transactional-shape-guide.md](transactional-shape-guide.md) rules 2, 3, 8).
14. **Writing a value from its rendering** — a count read as "once" because the rendering showed nothing, a case-insensitive test written as case-sensitive, a status text paraphrased or retyped with different spacing, a parsing rule worded from the command's name instead of from its use (Step 3).
15. **Making a scripting wrapper a library of verbs** — "Click by id", "Type by id" as public workflows — instead of the calling steps' UI actions on the elements its identities name (Step 3).
16. **Writing a suspected defect from a rendering.** A defect is marked only after the two passes of [defect-verification-guide.md](defect-verification-guide.md), the full rendering and then the framework's source itself. The mirror failure is just as bad: calling a rendering artefact, or a reader's own blind spot, a defect of the source. Other forms: a defect labelled "suspected" and left for the reader to check, a consequence asserted without tracing it through the bindings, and platform semantics nobody documented presented as fact.
17. **A related resource overriding the source**, or linked without being read (Step 3).
18. **Reading a source above one part's budget in one context, or fanning out before the shared decisions are fixed** — a reading cut short by compaction, components that name one asset several ways, the same question asked in several files (Step 2b, [extraction-parts-guide.md](extraction-parts-guide.md)).
19. **Rerunning a whole extraction for a changed source or a run cut short**, overwriting the steps that are still right and the user's edits with them ([editing-guide.md § Partial Re-extraction](editing-guide.md)).