feat: pre-edit verification gate for dependencies and activity tags

[AlvinStanescu]

Summary

Codifies two failure modes that surfaced in a recent
CertificateHandling_UploadToSharePoint session post-mortem — both
were avoidable and not yet covered by the skill docs:

1. Removing a dependency without searching for usages. The session
   removed UiPath.DocumentUnderstanding.Activities because it was a
   -preview package, which silently broke MergePDFs in
   MergeAttachments.xaml (the activity ships only in that package's
   bundled UiPath.IntelligentOCR.StudioWeb.Activities — preview is
   that family's only ship vehicle, not a stability defect).
2. Writing <ui:DeleteFile> from the Studio display name. The
   correct tag is <ui:Delete> (UiPath.Core.Activities.Delete,
   already documented under
   references/activity-docs/UiPath.System.Activities/26.4/). Bad tags
   pass get-errors and fail only at build, after the file is
   already serialized.

Plus two smaller post-mortem items:

• PowerShell scripts invoked from Invoke Process — PS 5.1 (the
  default powershell.exe) does not support Invoke-WebRequest -InFile, ConvertFrom-Json -AsHashtable, ternary, null-conditional,
  &&/||, etc. Nothing in the skill covered this; the session hit
  the Invoke-WebRequest -InFile trap and self-corrected after
  noticing the runtime error.
• Building PSArguments from XAML expressions without escaping
  embedded double-quotes — quote injection from any user-controlled
  path silently shifts every subsequent positional arg.

Changes

• skills/uipath-rpa/SKILL.md
  • New Critical Rule 6a "Pre-edit verification gate" covering both
    dependency removal and new activity tags, with cross-links to the
    detailed procedures.
  • New Task Navigation row pointing to the PowerShell interop guide.
• skills/uipath-rpa/references/project-structure.md
  • New "Removing a Dependency — Search for Usages First" section with
    the inspect-package + grep procedure.
  • New "-preview Is Not Always a Stability Smell" subsection with a
    get-versions --include-prerelease verification step and the
    known preview-only families.
• skills/uipath-rpa/references/xaml/common-pitfalls.md
  • New "Common Activity Name Confusions" section with display→tag
    mismatches and a tag verification gate.
  • Added s:Exception row to the x: vs s: namespace table for
    <Catch> and Throw authoring.
• skills/uipath-rpa/references/powershell-interop-guide.md (new)
  • PS 5.1 vs 7+ feature gap with migration patterns.
  • VB and C# expression forms for double-quote-escaping
    PSArguments.
  • Status-file and exit-code patterns for surfacing script outcomes,
    with the "always write the file, even on crash" + "delete after
    read" correctness rules.
• skills/uipath-review/SKILL.md
  • Anti-patterns 9 and 10 mirror the dependency-removal and -preview
    verification rules so the review skill does not generate the same
    bad recommendation that an authoring skill would now refuse to
    execute.

CLI flags in all new examples were verified against uip rpa --help /
the per-command --help output (inspect-package uses --package-name

• --package-version; get-versions uses --package-id;
  find-activities uses --query; install-or-update-packages uses
  --packages '[{"id":"…"}]').

Test plan

• bash hooks/validate-skill-descriptions.sh exits 0 (descriptions unchanged)
• No new broken cross-skill references introduced (the changes only add intra-skill links from uipath-rpa SKILL.md to its own references/)
• CODEOWNERS already covers the touched paths (uipath-rpa, uipath-review) — auto-request

🤖 Generated with Claude Code

[github-actions]

Claude finished @AlvinStanescu's task in 3m 26s —— View job

---

PR Review: Pre-edit verification gate for dependencies and activity tags

• Read review criteria and project conventions
• Read full PR diff
• Read existing PR conversation
• Read each changed file in full context
• Apply skill-specific checks (links, cross-refs, CODEOWNERS)
• Post review findings

---

Summary

Codifies two post-mortem failure modes (removing a dependency without searching usages, deriving XAML tags from display names) as a pre-edit verification gate in Critical Rule 6a, with supporting reference material. Also adds a new PowerShell interop guide covering PS 5.1 vs 7+ gaps and argument quoting. The review skill gains matching anti-patterns (9, 10) so it won't recommend the same mistakes.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md (+4 lines)

Severity: OK

Critical Rule 6a is well-structured — two clear sub-bullets for the two failure modes, each with a cross-link to the detailed procedure. The 6a sub-numbering is consistent with the existing 7a pattern. The Task Navigation row for PowerShell interop correctly links to the new guide. All three relative links resolve:

• references/project-structure.md#removing-a-dependency--search-for-usages-first ✓
• references/xaml/common-pitfalls.md#common-activity-name-confusions ✓
• references/powershell-interop-guide.md ✓

2. skills/uipath-review/SKILL.md (+2 lines)

Severity: OK

Anti-patterns 9 and 10 mirror the authoring rules independently (no cross-skill reference). Both are prescriptive: the agent is told exactly what to check (grep for assembly name, run get-versions --include-prerelease) before making a removal or preview recommendation. Consistent with the existing anti-pattern style.

3. skills/uipath-rpa/references/powershell-interop-guide.md (+135 lines, new)

Severity: Low

Well-structured reference guide. Covers PS version gap, argument escaping, and status-file patterns — all prescriptive with copy-paste examples. Anti-patterns section at the end. Both relative links resolve:

• xaml/common-pitfalls.md#invalid-use-of-x-prefix-for-non-builtin-clr-types ✓ (heading at line 591)
• ui-automation-guide.md#mandatory-generate-targets-before-writing-any-ui-code ✓ (heading at line 58)

One minor token-optimization note: some articles and filler survive ("When an RPA workflow shells out to", "If the workflow does not pin a version and uses"). The guide is clear enough that this is polish, not blocking.

4. skills/uipath-rpa/references/project-structure.md (+32 lines)

Severity: Medium (one issue)

The dependency-removal procedure and -preview subsection are solid. The get-versions command is correct. However:

project-structure.md:116-117 — Bash comment contradicts the command flag. The comment says # Get the package's full public type/activity surface as markdown but the command uses --output json:

# Get the package's full public type/activity surface as markdown
uip rpa inspect-package --package-name <PackageId> --package-version <Version> --output json

The canonical inspect-package-guide.md does not list --output json as a supported flag for this command. Either:

• --output json should be removed if inspect-package only outputs markdown, OR
• The comment is wrong and should be stripped entirely (per token-optimization rules, surrounding prose already explains intent)

Fix this →

5. skills/uipath-rpa/references/xaml/common-pitfalls.md (+23 lines)

Severity: OK

The "Common Activity Name Confusions" table is valuable — display-name → tag-name mismatches are exactly the kind of trap an agent hits. The Tag Verification Gate gives two clear options (doc check or CLI lookup) with the correct find-activities flag. The s:Exception row in the x: vs s: namespace table is correct and fills a real gap for <Catch> and Throw authoring.

What's Missing

• Token-optimization compliance in project-structure.md:116,121,123: Three bash comments that restate surrounding prose. Per token-optimization.md § Code Block Comment Stripping: "Strip when comment restates section heading or surrounding bullet point." The step-1 comment is also factually wrong ("as markdown" vs --output json). The step-2 comments are accurate but redundant with the numbered list text.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	No new skill folder; existing behavior unchanged
Skill Body	OK	Rule 6a + task navigation row well-placed
References & Assets	Issue	Minor: contradictory comment + --output json flag on inspect-package
Repo Hygiene	OK	CODEOWNERS covers both paths; no secrets; no cross-skill refs

Issues for Manual Review

• inspect-package --output json validity: The PR description says all CLI flags were verified against --help, but the canonical inspect-package-guide.md does not show --output json as a parameter. Verify whether inspect-package actually supports this flag — if it only outputs markdown, the --output json flag in project-structure.md:117 will silently be ignored or error.

Conclusion

Strong post-mortem codification — the two failure modes are real, the procedures are correct and prescriptive, and the cross-links are clean. One medium issue: the inspect-package command in project-structure.md has a contradictory bash comment and potentially incorrect --output json flag that should be verified and cleaned up. Everything else looks good.

---

[github-actions]

Claude finished @AlvinStanescu's task in 3m 10s —— View job

---

PR Review: Pre-edit verification gate for dependencies and activity tags

• Read review criteria and project conventions
• Read full PR diff (5 commits, net +94/-0 across 4 files)
• Read existing PR conversation (prior automated review resolved)
• Read each changed file in full context
• Apply skill-specific checks (links, cross-refs, CODEOWNERS)
• Post review findings

---

Summary

Codifies two post-mortem failure modes as Critical Rule 6a in the RPA skill: (1) removing a dependency without searching for usages, (2) deriving XAML tags from Studio display names. Adds a new PowerShell interop guide recommending InvokePowerShell<T> over Invoke Process, and mirrors the dependency/preview rules as anti-patterns 9–10 in the review skill. The project-structure.md additions from the initial commit were cleanly reverted in follow-up commits, leaving a tight 4-file, 94-line changeset.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md (+5 lines)

Severity: Low (one minor inconsistency)

Critical Rule 6a is well-structured — two clear sub-bullets matching the two failure modes. The 6a sub-numbering is consistent with the existing 7a pattern. The Task Navigation row for PowerShell interop correctly links to the new guide. All relative links resolve:

• references/powershell-interop-guide.md ✓
• references/xaml/common-pitfalls.md#common-activity-name-confusions ✓ (heading at line 434)

One minor inconsistency (SKILL.md:75): The decision table row says "never Invoke Process + powershell.exe" — an absolute prohibition. But the new PowerShell guide has a "Last-Resort Invoke Process" section (line 53) documenting exactly when to use it. The guide's nuanced view is more accurate; the table's "never" could mislead an agent into refusing Invoke Process even when InvokePowerShell genuinely can't work (vendor-CLI scenarios). Consider softening to "avoid Invoke Process" or "prefer InvokePowerShell<T> — see guide for last-resort cases."

2. skills/uipath-review/SKILL.md (+2 lines)

Severity: OK

Anti-patterns 9 and 10 are self-contained (no cross-skill reference). Both are prescriptive — the agent is told exactly what to check before making a removal or preview recommendation. Consistent with existing anti-pattern style and numbering.

3. skills/uipath-rpa/references/powershell-interop-guide.md (+68 lines, new)

Severity: OK

Well-structured reference guide with a clear message hierarchy: coded workflow > InvokePowerShell<T> > Invoke Process last resort. The InvokePowerShell property table is useful. Both relative links resolve:

• coded-vs-xaml-guide.md ✓ (exists at references/coded-vs-xaml-guide.md)
• ui-automation-guide.md#mandatory-generate-targets-before-writing-any-ui-code ✓ (heading at line 58)

Token-optimization compliance is good — the guide was trimmed from 143 to 68 lines across the follow-up commits.

4. skills/uipath-rpa/references/xaml/common-pitfalls.md (+19 lines)

Severity: OK

The "Common Activity Name Confusions" table is valuable — display-name → tag-name mismatches are exactly the trap an agent hits. The Tag Verification Gate gives two clear lookup options with correct CLI flags (find-activities --query --output json). The s:Exception row in the x: vs s: namespace table fills a real gap for <Catch> and Throw authoring.

SKILL.md Rule 6a links here with a See [common-pitfalls.md §] bridge — correct reference-pointer discipline with no substantive duplication.

What's Missing

• project-structure.md dependency-removal procedure was removed. The initial commit added a detailed inspect-package + grep procedure, -preview verification step, and known preview-only families list. Follow-up commits reverted all of it. Rule 6a now inlines a brief version ("grep the project for usages first"), but the full procedure (enumerate activity surface → grep → decide) and the get-versions --include-prerelease verification step no longer exist anywhere in the skill. This is arguably fine for SKILL.md brevity, but agents attempting the dependency-removal workflow have no detailed reference to follow. Consider whether a trimmed version of the procedure belongs in project-structure.md as a cross-linked reference.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	No new skill folder; existing behavior unchanged
Skill Body	OK	Rule 6a + task navigation row well-placed
References & Assets	OK	New PS guide is clean; common-pitfalls additions are accurate
Repo Hygiene	OK	CODEOWNERS covers both paths (/skills/uipath-rpa/, /skills/uipath-review/); no secrets; no cross-skill refs

Issues for Manual Review

• InvokePowerShell<T> property accuracy. The property table (powershell-interop-guide.md:21–29) was verified against find-activities and DLL strings per the commit message, but the Parameters collection's element type and PowerShellProcess enum values should be confirmed against actual runtime behavior.
• "never Invoke Process" vs "Last-Resort" inconsistency (SKILL.md:75 vs powershell-interop-guide.md:53). Low severity but worth a decision: either soften the table or remove the last-resort section.

Conclusion

Clean, well-motivated post-mortem codification. The two core failure modes are correctly captured in Rule 6a with appropriate cross-links. The PowerShell guide is solid after the follow-up rewrites. One low-severity inconsistency between the SKILL.md table ("never Invoke Process") and the guide ("Last-Resort Invoke Process"). The reverted project-structure.md content leaves a gap in detailed dependency-removal procedures — worth considering whether to restore a trimmed version. Otherwise ready to merge.

---

[gabrielavaduva]

removing dependencies should be done by a tool from rpa e.g. remove-unused-dependencies

[AlvinStanescu]

true, we should have such a tool instead

[AlvinStanescu]

Agreed — reframed the bullet to acknowledge a CLI tool (e.g. remove-unused-dependencies) is the right enforcement point; grep is the fallback until it ships.