Skip to content

refactor(uipath-rpa): mode-partition SKILL.md + coded service quick card (T3) - #1458

Closed
RaduAna-Maria wants to merge 1 commit into
fix/skill-dedup-t2from
fix/rpa-mode-partition-t3
Closed

RaduAna-Maria wants to merge 1 commit into
fix/skill-dedup-t2from
fix/rpa-mode-partition-t3

Conversation

@RaduAna-Maria

Copy link
Copy Markdown
Collaborator

Summary

Tranche 3, stacked on #1457. The highest-token-ROI change in the series: uipath-rpa's SKILL.md is mode-partitioned so coded consumers stop paying for XAML/UIA rules and vice versa, plus a provenance-traced service quick card that replaces generated API-dump reads for common scenarios.

Merge gate (measured)

The audit's original simulation scenario ("create a coded workflow project that reads Excel rows into an Orchestrator queue, validate it") re-run against this branch, same protocol:

Metric Baseline (main) This branch
Files read 11 10
Words read 32,900 18,289 (−44%)
Useful share 32% 49%
Completeness verdict complete complete — init flags, .cs structure, Excel + queue signatures, validation loop all reached
Dead ends / broken links 1 chicken-and-egg 0

Gate-flagged required fixes (all addressed in this PR): packages-install documented 4× → canonical in cli-reference; verbatim A/B/C escalation template duplicated coding-guidelines↔validation-guide → single home; stray @../validation-guide.md include; Build/run/validate nav-chain order; project-structure.md vs project-structure-guide.md collision → mutual scope lines; quick-card queue semantics (doc-sourced only); Excel COM-vs-Portable framework trap in Rule 2a.

Structure

  • SKILL.md 7,603 → 4,970 words; Critical Rules + Task Navigation moved to directly after "When to Use" (router at ~30%, was 57%)
  • XAML Rules 16–24 + XAML quick reference → references/xaml/critical-rules-xaml.md (numbers preserved; read-in-full gate stays in SKILL.md)
  • Coded tables (file types, service→package, built-ins, templates) → references/coded/critical-rules-coded.md
  • Rule bodies deduplicated against references that already owned them verbatim (validation-guide, trigger-pattern-guide, debugging, tenant-library-search-guide, uia-prerequisites — the last also fixing a real disagreement on the CLI-unavailable fallback ladder)
  • All 14 inbound Critical Rule N citations updated to name the new files (including 8 bundled activity docs)
  • codedworkflow-reference.md reduced to unique content; its dead "infrastructure packages" pointer fixed

Quick card

references/coded/service-quick-card.md (~750 words): system (queues, assets, credentials), excel (Portable + Interop surfaces), testing (verifications, test data) — every signature copied from the bundled activity-docs with per-row provenance (in the PR-linked agent report), zero prior-knowledge content. UIA row is a pointer only, per the skill's CLAUDE.md boundary. Wired as step 0 of the coded API resolution order; escalation rule sends agents to the full coded-api.md only when a signature/overload/enum is missing.

Validation

  • scripts/check-cross-skill-links.py — OK
  • hooks/validate-skill-descriptions.sh — pass (426 chars, frontmatter untouched)
  • All links in touched files resolve; no forbidden UIA strings (per skills/uipath-rpa/CLAUDE.md) in moved or new prose
  • Rule-by-rule disposition table in the commit message; zero information loss verified

🤖 Generated with Claude Code

…k card

SKILL.md 7,603 → 4,970 words; Task Navigation router moved from 57% to ~30%
into the file. XAML Rules 16-24 + XAML quick reference →
references/xaml/critical-rules-xaml.md (read-in-full gate kept in SKILL.md);
coded reference tables → references/coded/critical-rules-coded.md; long
rule bodies deduplicated against the references that already owned them
verbatim (validation-guide, trigger-pattern-guide, debugging,
tenant-library-search-guide, environment-setup, uia-prerequisites — the
last also resolving a real disagreement on the no-CLI fallback ladder).
All 14 inbound rule citations updated to name the new files.

New references/coded/service-quick-card.md (~750 words): most-used
system/excel/testing signatures, 100% provenance-traced to the bundled
activity-docs; wired as step 0 of the coded API resolution order. Replaces
~11.8k words of generated API-dump reading for common scenarios.

Merge gate — the audit's original simulation scenario re-run against this
restructure: 32,900 → 18,289 words read (−44%), usefulness 32% → 49%,
verdict complete (init flags, .cs structure, Excel + queue signatures,
validation loop all reached). Gate-flagged friction fixed in this commit:
packages-install dedup (validation-guide → cli-reference pointer),
verbatim A/B/C escalation template dedup (validation-guide owns it), stray
@-include in coding-guidelines, Build/run/validate nav-row order,
project-structure.md vs project-structure-guide.md mutual disambiguation,
queue-semantics note on the quick card (doc-sourced), Excel
COM-vs-Portable clarification in Rule 2a.

codedworkflow-reference.md reduced to its unique content (IS connections,
hooks, job context); built-in methods table folded into
critical-rules-coded.md; dead infra-packages pointer fixed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jun 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @RaduAna-Maria's task in 3m 6s —— View job


PR Review: refactor(uipath-rpa): mode-partition SKILL.md + coded service quick card (T3)

  • Read review criteria and project conventions
  • Run full diff against base branch
  • Read existing PR conversation
  • Review SKILL.md changes
  • Review new files (critical-rules-coded.md, critical-rules-xaml.md, service-quick-card.md)
  • Review modified reference files
  • Verify all relative links resolve (89+ links — all OK)
  • Check for cross-skill references, secrets, UIA boundary violations
  • Post final review

Summary

Mode-partitions the uipath-rpa SKILL.md so coded consumers stop paying for XAML rules and vice versa. XAML Critical Rules 16–24 + quick reference moved to references/xaml/critical-rules-xaml.md; coded tables (file types, service-to-package, built-ins, templates) moved to references/coded/critical-rules-coded.md. A new service-quick-card.md provides provenance-traced signatures for the most-used coded service calls. All 14 inbound "Critical Rule N" citations across activity docs are updated to point to the new files. SKILL.md drops from ~7,600 to ~4,970 words while retaining all information.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md — Major restructure

Severity: OK

Well-executed partition. Critical Rules section now: Common 1–12 inline, Coded 13–19 inline with a pointer to critical-rules-coded.md for supporting detail, XAML 16–24 fully extracted to critical-rules-xaml.md with a read-in-full gate. Key observations:

  • Section reordering is sound. Critical Rules + Task Navigation now appear before the lower-priority Precondition/Step 0/Project Type Detection/Authoring Mode Selection sections. Router content arrives at ~30% of the file instead of ~57% — a meaningful improvement for token efficiency.
  • Reference pointer discipline is clean. Sections that were moved out (XAML rules, coded tables, Capture-First Fast Path details, project-context discovery procedure) are replaced with bridge sentences + links. No content duplication between SKILL.md and the extracted references.
  • Rule 2a Excel COM/Portable clarification is a nice addition: excel.UseWorkBook is Portable-safe; only UseExcelFile (COM/interop) requires Windows. This is new information, not just a move.
  • Capture-First Fast Path correctly defers full procedure to ui-automation-guide.md § Capture-First Fast Path (where the detailed steps now live), keeping SKILL.md to a bridge sentence.
  • Validation-guide reference in Rule 3 now says "read before the session's first validate/build" — clearer guidance on when to read it.
  • Rule 12 trigger compression is well done — retains all decision-critical info (integration = strict, local = flexible, unknown = ask) while eliminating the multi-paragraph expansion.

2. references/coded/critical-rules-coded.md (NEW)

Severity: OK

Clean extraction. Contains the three .cs file types table, service-to-package mapping, CodedWorkflow built-in methods table, workflow invocation patterns (recommended workflows.* vs fallback RunWorkflow), and template links. All content was previously in SKILL.md. Relative links to codedworkflow-reference.md, operations-guide.md, integration-service-guide.md, and template assets all resolve.

3. references/coded/service-quick-card.md (NEW)

Severity: OK

High-value addition. Covers system (queues, assets, credentials), excel (Portable UseWorkBook and Windows UseExcelFile surfaces), testing (verifications, test data), and a uiAutomation pointer (correctly defers to ui-automation-guide.md per the UIA boundary rules). The escalation rule ("signature not here → read coded-api.md") is clear. Platform-types callout and queue-semantics notes add useful context.

One minor observation: the testing package version is pinned as "[25.10.2]" — this is specific enough that it could drift, but since it's a signature-sourcing doc rather than an install instruction, it's acceptable as provenance.

4. references/xaml/critical-rules-xaml.md (NEW)

Severity: OK

Faithful extraction of XAML Rules 16–24 plus the XAML Workflows Quick Reference (workflow types, expression language, key CLI commands, common activities, XAML file anatomy, key references). Rule numbering preserved. All relative links resolve (uses ../ correctly for cross-directory references to common-activity-card.md, ui-automation-guide.md, reframework-guide.md, etc.).

5. Activity docs updates (8 files: Delay, If, Rethrow, Sequence, Switch, Throw, TryCatch, WriteLine)

Severity: OK

Mechanical update: "per Rule 24" → "per Rule 24 (references/xaml/critical-rules-xaml.md)" and similar. Consistent, correct, and all point to the right file.

6. references/coded/codedworkflow-reference.md

Severity: OK

Reduced to unique content (Integration Service connections, services property, job context, Before/After hooks). Built-in methods table and workflow invocation section moved to critical-rules-coded.md with a clean pointer. The dead "infrastructure packages" pointer noted in the PR description is fixed — the intro now correctly routes to critical-rules-coded.md.

7. references/coded/coding-guidelines.md

Severity: OK

Two changes: (1) Stray @../validation-guide.md include replaced with a proper link sentence. (2) Verbose A/B/C escalation template removed and replaced with pointer to validation-guide.md § Smoke Test — eliminating the duplication the PR description flagged.

8. references/environment-setup.md

Severity: OK

Project Context Discovery procedure (staleness check + discovery flow) moved here from SKILL.md. This is the right home — environment-setup already owns the PROJECT_DIR resolution and template selection procedures. SKILL.md's § Precondition: Project Context now bridges to this section.

9. references/ui-automation-guide.md

Severity: OK

Two new sections: (1) Capture-First Fast Path — the full 4-step procedure with skip conditions, moved from SKILL.md. (2) UIA Activity Pack Doc Map — the bullet list of UIA package doc paths, moved from SKILL.md's § UI Automation References. Both are the correct authoritative home for this content. The "Running a UIA workflow" section also gained one sentence about run behavior during capture — previously only in SKILL.md.

10. references/uia-prerequisites.md

Severity: OK

Rule 7a's fallback ladder (package-below-minimum → placeholder stubs vs indication capture) moved here from SKILL.md. This was a real disagreement fix noted in the PR description — the CLI-unavailable fallback now lives in one place rather than differing between SKILL.md and this file.

11. references/validation-guide.md

Severity: OK

Package Error Resolution section compressed from a multi-line code block + bullet list to a single sentence with a pointer to cli-reference.md § packages install. Clean dedup — the procedure detail is already in cli-reference.md.

12. Other reference updates (common-activity-card, project-structure-guide, project-structure, trigger-pattern-guide, xaml/*.md)

Severity: OK

Mechanical updates: "Rule 21" → "Rule 21 (critical-rules-xaml.md)" and similar. project-structure.md and project-structure-guide.md gain mutual scope lines to resolve the collision noted in the PR description. All links resolve.

What's Missing

Nothing identified. The PR is well-scoped and complete.

Area Ratings

Area Status Notes
Frontmatter OK Untouched (426 chars)
E2E Tests OK Not applicable — no new skill, and these are doc restructuring changes that don't alter CLI workflows
Skill Body OK Clean mode-partition; Critical Rules → Task Navigation now front-loaded; all extraction is lossless
References & Assets OK 3 new files well-structured; 89+ relative links all resolve; no orphaned files; UIA boundary clean
Repo Hygiene OK No secrets, no cross-skill refs, no new skill path (CODEOWNERS N/A)

Issues for Manual Review

  • Service-quick-card signature accuracy: The PR description states signatures were "copied from bundled activity-docs with per-row provenance." I verified the card's structure and link discipline, but cannot independently verify that each C# signature matches the actual UiPath SDK API surface. The provenance claim is credible given the methodology described.
  • Token-reduction metrics: The PR claims −44% words read for the simulation scenario. The structural changes support this (coded consumers skip XAML rules; XAML consumers skip coded tables), but the exact numbers are from an external simulation I cannot reproduce.

Conclusion

Clean, well-scoped refactoring that achieves its stated goal: mode-partition uipath-rpa's SKILL.md so agents only pay for the rules they need. The extraction is lossless — every rule, table, and procedure lands in exactly one authoritative home. Reference pointer discipline is good throughout: bridge sentences link to references without restating them. The service quick card is a high-value addition for coded workflow scenarios. No issues found that would block merge.

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.

1 participant