docs(skill): add model editing + split uipath-process-mining into domain + CLI-mechanics layers - #2411
Draft
dgeelen-uipath wants to merge 16 commits into
Draft
docs(skill): add model editing + split uipath-process-mining into domain + CLI-mechanics layers#2411dgeelen-uipath wants to merge 16 commits into
dgeelen-uipath wants to merge 16 commits into
Conversation
Start the user-facing Process Mining authoring skill for `uip pm`: end-to-end CSV → queryable process app. Covers app lifecycle + dev/published stages, the ELT editor (dbt transformation) operations, getting the data model into shape — including the add-table pattern to expose custom analytical tables (instead of repurposing Tags/Due_dates) — the query surface (--group-by/--metric sugar + aggregate AST), and where process-app RBAC is configured. SKILL.md + references: pre-flight, transformations, data-model, querying, lifecycle-and-rbac. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The mapping → upload → ingest → transform → data-model → query pipeline is template-agnostic; only the mapping/extract differs. Add references/app-types.md (custom vs source-system families, same model shape, how to discover/target any template, what is custom-specific), generalize the SKILL.md framing + template- selection rule, mark the Cases.sql gotcha as custom-only, and note in pre-flight how to map to a source template's expected input tables (via sources.yml). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fold in the registration scaffolding (from the now-closed #1989) so the skill is complete: CODEOWNERS ownership, README status row, skill-status.json entry (preview). Add two coder-eval tasks written to the lint rubric — goal-oriented prompts (not step recipes) with meaningful per-command validation: - app_types_discovery_smoke: skill-triggered + `pm app-types list` - custom_app_pipeline_e2e: create(uipath.custom) → upload → ingest → transformations Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ection Apply Claude review feedback on #2252: - Reference Pointer Discipline: Critical Rule 1 no longer inlines the Tables[] JSON + Kind semantics (they live in references/data-model.md) — keep a one-line summary + link. - Add a dedicated "Anti-patterns — what NOT to do" section (expected final body section per skill-structure rules), consolidating the inline anti-pattern notes. - querying.md: make the event-table restriction workaround prescriptive (insights / layout, or precompute + add-table). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… custom tables Reflect the new CLI capability (UiPath/cli#3218): register a custom dbt model as a queryable data-model table post-create with `uip pm apps model add-table <app> --file <table.json>` (GET-merge-PUT, ETag-safe), and inspect with `apps model get`. Update Critical Rule 1 + references/data-model.md (recommended post-create flow, camelCase entry shape, full recipe). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Correct the add-table guidance to the proven, case-centric flow and
document when to use the built-in Case-child tables.
- Process Mining is case-centric: a queryable table must be the Cases root
or reach Cases via a foreign key; an unlinked table fails at query time
with UserError_TableIsDeleted.
- add-table edits the STRUCTURAL data model (/dev/dataModel: DataModelDto
{ name, primaryKey, foreignKeys }), not the semantic model, then
applyCurrentDatamodel — and the table is inert until the next re-ingest.
- Loose-link a standalone analytical table with a surrogate PK + nullable
Case_ID FK to Cases.
- New decision table for the template's built-in Case-child slots:
Tags (multi-valued per-case labels: Tag/Tag_type) and Due_dates (per-case
SLA/deadline: Expected/Actual/On_time/Cost/Difference) — populate their
dbt stubs when the data fits, instead of hand-rolling add-table.
- Reframe the Tags/Due_dates anti-pattern: populating them with their real
semantics is intended; smuggling unrelated analytics through them is not.
`apps create --data-mapping` used to be the only way to set an input data mapping, so the skill had no answer for "my mapping is wrong" other than building a new app — which also discards any transformations already patched. UiPath/cli#3300 adds `uip pm apps data-mapping get|update`, so document the in-place fix loop. - New Critical Rule 5 (rules 5-8 renumbered, cross-refs updated): read → edit → update → re-ingest, and why this is NOT the Rule 4 apply loop — a mapping governs parsing, so `transformations apply` after a mapping edit looks successful and changes nothing. - Quick Start step 4b; anti-patterns for recreating the app and for reaching for `apply`; frontmatter routing for "fix/change my data mapping" / "do I have to recreate the app". - `references/pre-flight.md`: the fix-loop recipe plus the field-tested failure modes — dev-only PUT (`published` is read-only), 409 `UserError_ETagFileConflict` on a stale/absent `If-Match`, 403 `UserError_NotAuthorized` (not 404) for an unreadable app, 400 leaving the stored mapping intact, the local table-less guard, and the never-published `published` stage answering with the template's mapping (`ETag: W/"0"`, `UseInLoad: false`). - New eval task `mapping_fix_in_place.yaml`: scores the get → update → re-ingest sequence and fails on `apps delete`/`apps create`, on re-uploading unchanged source data, and on `--stage published`. Also corrects two casing/output claims to match what shipped: `get --destination` writes the API response verbatim (camelCase) while the envelope's `Data.Mapping` is PascalCased, and `update` reports `Tables` + `IngestionNeeded` rather than a new ETag. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…y items Addresses the remaining items from Claude's review now that `uip pm` has shipped to cli main, so the surface is verifiable rather than speculative. Tests (the review's "No test tasks" finding, and the CI untested-skill warn): - add_table_queryable — Rule 1, the headline rule: register a custom dbt model as a Case-linked data-model table and RE-INGEST. Negative criteria fail the run if the agent repurposes Tags.sql/Due_dates.sql, the exact hack the rule exists to prevent; asserts the table file carries a foreignKeys→Cases link, since an unlinked table registers fine and then fails every query with UserError_TableIsDeleted. - transform_fix_apply_not_reingest — Rules 3 + 4: the Cases.sql optional-column gotcha, fixed with get → update → apply. Negatives fail a re-upload or re-ingest, which re-push the whole dataset for nothing. Deliberately the mirror of mapping_fix_in_place, where a re-ingest IS required — together they pin the direction agents get backwards. - query_group_by_sugar — Rule 6: use --group-by/--metric rather than a hand-written aggregate AST with bare column names (UserError_FieldNotFound), and stay inside the AggregationFunction enum. Verified against the shipped CLI, closing the review's "CLI command accuracy" item: every command path and every flag the skill documents exists (all 7 query subcommands incl. details/rca/insights, which are registered through a spec loop), and the aggregation enum is exactly average|count|sum|min|max per AGGREGATIONS in query.ts. Also closes "Publishing workflow": lifecycle-and-rbac.md no longer hedges about whether a publish verb exists — `uip pm apps publish` does. Document its model-version precondition and that IngestionNeeded means the promoted definition still needs a re-ingest to reach the data. SKILL.md's command inventory now lists publish and the model subgroup. The review's `when_to_use` question resolves as intentional: 11 of 25 skills in this repo use the field. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…g cap The pre-commit validator only caps `description` at 1024, but the operative limit is the one its own comment documents: Claude Code truncates the COMBINED `description` + `when_to_use` at 1,536 chars in the skill listing. Growing both fields for the data-mapping routing pushed the pair to 1698 — 162 over — and truncation takes the tail of `when_to_use`, which is exactly where the new triggers had been appended. The routing keywords added to make "fix my data mapping" reach this skill would have been the first thing cut, silently, with CI green. Tighten both fields to 1485 combined (~51 chars headroom) with every trigger retained: data mapping, wrong date format, recreate the app, add a table, Cases.sql. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`tests/tasks/activation/` had a jsonl for every covered skill except this one (and uipath-connector-builder), so the activation eval never measured whether uipath-process-mining fires when it should — or, just as important, whether it steals prompts belonging to sibling skills. That is the only test that actually exercises the frontmatter routing, which the previous commit showed is easy to break silently. 14 positives spanning the skill's trigger surface: build-from-CSV, template discovery, ingest, the Cases.sql failure, "why can't I query my custom table", add-table, group-by/metric, the mapping fix loop (both the "do I have to recreate the app?" and read/change phrasings), throughput and rework, publish, dbt editing, steps-to-resolution, and mapping warnings. Registered in activation.yaml's dataset.paths plus a 24th skill_triggered criterion, keeping paths and criteria 1:1 (verified: 25 paths = 24 skills + negative.jsonl, 24 criteria, no path without a criterion or vice versa). Stale "23 criteria" counts in activation.yaml and the activation README updated to 24. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Match the precedent set by uipath-functions and uipath-troubleshoot, so the team that owns the skill also reviews changes to the activation prompts that gate its routing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ning `negative-031` — "Set up UiPath Process Mining to analyze bottlenecks in my procure-to-pay process" — was labelled `expected_skill: ""` because no process-mining skill existed when the negatives were written. It is now a textbook positive: the P2P template plus bottleneck/throughput analysis is exactly what this skill covers. Left as-is it guarantees a scored false positive for uipath-process-mining the first time the activation eval runs, depressing its precision for doing the right thing. The negatives set is documented as prompts that should fire NO skill — including adjacent UiPath products — but this names the very product the skill is for, so it is a positive, not an adjacency. Moved to uipath-process-mining.jsonl as -015 (15 positives). Swept the rest of negative.jsonl for the same staleness: no other negative mentions process mining, `uip pm`, an event log, or a data mapping. Fixtures verified repo-wide — 1314 rows, all ids unique, keys valid. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…s, calculated fields) Stacked on #2252. Adds references/model-editing.md covering the app-model editing surface the CLI now exposes: changing a field's data kind (numeric→duration), calculated fields, the semantic (`apps model`) vs structural (`apps data-model`) split, and the data-kind comparison rule that locks an app open (DNA-46960: lt(duration, numeric)). Mechanical first pass — this pairs with a UiPath/cli change that renames `apps model`→`apps data-model` and adds `apps model` (semantic) + `fields`; follow-up will align the base skill's `apps model add-table`/`get` references and integrate the prose. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`--kind` accepts only the eight user-settable data kinds; `id` and `ref` are structural (system-assigned to key/reference columns) and cannot be set, so listing them alongside the settable kinds misleads. Mirrors the CLI, whose `fields set --kind` choices exclude them.
…ence The skill fused "what process mining is / what to build and why" with "how to drive the uip pm CLI", so the mechanics (command-group map, the Result/Code/Data envelope, the ETag get-modify-put pattern, --wait, --stage, field-id discovery, the Quick Start) were repeated inline in SKILL.md and scattered across the topic references. Extract that shared plumbing into references/uip-pm-cli.md and frame SKILL.md as the domain layer that carries the decisions and links down to it — progressive disclosure, one skill, no second activation surface. Also realign the structural-model command names to the merged CLI: the table graph is now `apps data-model get|add-table` (the `apps model` name now addresses the semantic model), and elevate the model-editing / data-kind lockout (DNA-46960) from a reference-only note to a Critical Rule + anti-pattern so the domain layer names the footgun.
A six-lens agent review (accuracy, agent-simulation, layering, domain,
editing, activation) surfaced fixable gaps:
- Activation recall: the new model-editing / data-kind-lockout capability was
absent from `description` + `when_to_use` (the only fields that drive
activation) and had no positive fixtures, so its own target prompts ("dashboards
won't open / Must be duration not numeric", "change a field's data kind") would
miss. Add the trigger phrases (description now 981/1024) and 4 positive + 3
adversarial-negative fixtures (guarding the generic data-type boundary).
- Accuracy: `query --stage published` is unreachable via the CLI (no `uip pm` path
completes a published-stage ingestion — live-verified in the CLI's query.md S7),
yet the skill steered consumers there. Add the CLI caveat in SKILL.md,
lifecycle-and-rbac.md, and querying.md.
- DNA-46960 clarity: reconcile "fields set validates and refuses" with the footgun
— the CLI validates synchronously (safe); the data-manager UI defers to re-ingest
(the vector), and view-only conflicts aren't caught.
- Domain: warn that a null-`Case_ID` loose-link table is analytically disconnected
(case filters don't propagate); soften "semantic model is derived" to "reconciled"
so add-table isn't read as wiping calculated fields/metrics.
- Mechanical: fix a `references/references/data-model.md` self-link, align Due_dates
field names to `Expected_date`/`Actual_date`, `datakind`->`data kind`, note
`Instructions` appears on some successes, and stop uip-pm-cli.md referencing
SKILL.md upward (keep the layer dependency one-directional).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Builds on the new
uipath-process-miningskill (#2252) with three things, from an actual DNA-46960 investigation driven end-to-end through theuip pmCLI:references/model-editing.md: editing a field's data kind (e.g. numeric→duration), calculated fields, the two models (semanticapps modelvs structuralapps data-model), and the data-kind comparison rule that locks an app open. Surfaces as Critical Rule 10 + an anti-pattern + aWhen to Usebullet.SKILL.mdis now the process-mining domain layer (what to build and why); the low-leveluip pmmechanics (command-group map, theResult/Code/Dataenvelope, the ETag get-modify-put pattern,--wait,--stage,IngestionNeeded, field-id discovery, the Quick Start) are extracted into a newreferences/uip-pm-cli.md. Progressive disclosure, unidirectional high→low. Also realigns the structural-model command names to the merged CLI (apps data-model get|add-table;apps modelnow addresses the semantic model).--stage publishedcaveat (unreachable viauip pm— no path completes a published-stage ingestion), reconciled the DNA-46960 "CLI validates synchronously vs data-manager UI defers" story, and fixed several mechanical nits (areferences/references/…self-link,Due_datesfield names, adatakind→data kindtypo).Why
Investigating DNA-46960 — a customer whose dashboards wouldn't open (
"Must be duration, not numeric, for the 'lt' input"; only the data-upload module reachable) because a metric compared adurationfield to anumericconstant — required inspecting and editing field data kinds and calculated fields, which the skill didn't cover. The companion CLI support landed in UiPath/cli#3345 (merged).Test plan
hooks/validate-skill-descriptions.shpasses (description981/1024).activation.yaml(no new skill, so no yaml change).apps model add-table/ structural-name references remain.🤖 Generated with Claude Code