refactor(uipath-rpa): consolidate co-read references (Stage 1)

[AlvinStanescu]

What

Merges uipath-rpa reference files that agents always read together in the same task flow, so each flow costs fewer sequential `Read` turns. 23 files absorbed (12 modern references, 3 asset templates, 8 legacy files), every merged file stays at or near the ~12k-token soft cap, and all inbound links (including SKILL.md's Task Navigation) are retargeted. Full plan + measured results: docs/uipath-rpa-v2.md.

Reads per flow (before → after): XAML create 6–9 → 4–5 · UIA 3–4 → 2 · coded 3–5 → 1–2 · Flowchart 3–4 → 2 · IS-connector XAML 2 → 1 · legacy project create 5 → 1.

Merge map

Survivor	Absorbed
cli-reference.md	validation-guide.md, publishing-guide.md, CLI pitfalls §
xaml/xaml-basics-and-rules.md	xaml/workflow-guide.md (IS internals moved out)
xaml/canvas-layout-guide.md	xaml/flowchart-guide.md, x:Reference wiring §
xaml/csharp-activity-binding-guide.md	xaml/csharp-expression-pitfalls.md
ui-automation-guide.md	uia-prerequisites.md (+UIA XAML gotchas; OR-UI-Library § → library guide)
uia-configure-target-workflows.md	uia-elements-interaction-guide.md
coded/operations-guide.md	coded/coding-guidelines.md
coded/codedworkflow-reference.md	coded/inspect-package-guide.md, coded/third-party-packages-guide.md
environment-setup.md	project-structure.md, project-structure-guide.md
is-connector-xaml-guide.md	connector-capabilities.md (~70% duplicate)
assets/codedworkflow-template.md	testcase / helper-utility / before-after-hooks templates
legacy: cli-reference.md ← 4 files · xaml-basics-and-rules.md ← common-pitfalls.md · selector-guide.md ← UIAutomation.md · testing-guide.md ← test-data-guide.md + Testing.md

Fixed along the way

• Personal path `C:\Users\alexandru.roman...` removed from `_REFRAMEWORK.md` / `_DU-PROCESS.md` (repo rule violation); forum-link "Sources" dumps reduced to official docs links.
• Cross-skill file links in publishing content and `coded/integration-service-guide.md` converted to self-contained CLI pointers with graceful skill-name delegation (self-containment rule).
• Broken pointer `coded/inspect-package-guide.md:3` (`references//examples.md` never existed) fixed; the previously orphaned bundled `activity-docs///coded/` docs are now wired as the documented third-tier fallback (`.local/docs` → `packages inspect` → bundled coded docs).
• Byte-identical duplicated section (34 lines) removed from `xaml/common-pitfalls.md`; `NGetText` skip-tax now stated once (was 4×).
• Pre-existing unclosed code fences (trailing ``` on command lines) fixed in three files.
• Cross-skill touch: one line in `skills/uipath-test/references/publish-and-link-guide.md` retargeted (it deep-linked `publishing-guide.md`, now absorbed into `cli-reference.md § Pack & Publish`).

Verification

• Link + anchor integrity: 0 problems across 700 markdown files (checker output in the plan doc; every relative link resolved, every `#anchor` matched against GitHub-style heading slugs).
• `hooks/validate-skill-descriptions.sh` ✅ · `scripts/check-skill-status.py` ✅ (frontmatter `description` untouched → no activation-gate recall eval).
• All merged files < 1,000 lines (Read-tool limit is 2,000); token audit table in the plan doc. Three files sit 3–6% over the soft ~12k cap (`ui-automation-guide` 12.7k, `xaml-basics-and-rules` 12.4k, `common-pitfalls` 12.3k) — each absorbed always-co-read content; splitting them back would re-add a Read per flow.
• Speed A/B (to run after CI): `/skill-compare main feat/uipath-rpa-consolidate-refs uipath-rpa 3` — hypothesis: merging co-read references cuts 2–4 reference-read turns per task and reduces duration/tokens without reducing success rate.

Known interactions

• Conflicts with draft PR feat(uipath-rpa): execution maps + pattern card — cut greenfield builds from ~36-40 to ≤10 turns #1827 (`feat/uipath-rpa-execution-maps`) on `SKILL.md`, `xaml/workflow-guide.md` (deleted here, edited there), `environment-setup.md`, and the two UIA files. Whichever lands second rebases; feat(uipath-rpa): execution maps + pattern card — cut greenfield builds from ~36-40 to ≤10 turns #1827's workflow-guide edits port into `xaml-basics-and-rules.md § Authoring Workflow`.
• Noticed, intentionally untouched: the pre-existing tension between the anti-pattern "never generate XAML without `get-default-xaml` as a starting point" and Rule 21a's card fast-path (card activities skip `get-default-xaml`). Flagging for a follow-up rather than changing semantics in a mechanical PR.
• Stage 2 (SKILL.md slim 16k → ~12k) follows as a separate PR stacked on this branch.

🤖 Generated with Claude Code

[github-actions]

Claude finished @AlvinStanescu's task in 13m 4s —— View job

---

PR Review: refactor(uipath-rpa): consolidate co-read references (Stage 1)

• Read review criteria and project conventions
• Analyze full diff (60 changed files, 3331+/3909-)
• Verify link integrity — all retargeted anchors verified against actual headings
• Check for secrets/personal paths — clean; personal path removal confirmed
• Review merged file quality — all 17 merged files under 1000 lines, content verified
• Validate SKILL.md frontmatter and link retargeting
• Check cross-skill touch (uipath-test) and repo hygiene
• Post final review

---

Summary

Mechanical reference-consolidation PR that merges 23 always-co-read files into their logical survivors, deletes the absorbed originals, and retargets all inbound links (including SKILL.md's Task Navigation table). The merge map is well-reasoned — files paired by actual co-read patterns — and the execution is thorough. Net effect: −578 lines, fewer sequential Read turns per agent task flow, no content loss.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md — Link retargeting

Severity: OK

All 30+ retargeted links verified: every anchor (#pack--publish-to-orchestrator, #validation-iteration-loop, #smoke-test, #coding-guidelines, #common-issues-and-fixes, #inspect-nuget-package-tool-on-demand-api-discovery, #third-party-nuget-packages, #designing-project-structure, #project-structure-reference, #phase-1-discovery, #4-state-machine-layout, etc.) resolves to an actual heading in the target file. Frontmatter description and when_to_use untouched — no activation-gate eval needed.

2. Modern track merges — all files under 1000 lines

Severity: OK (with issues noted separately below)

File	Lines
legacy/cli-reference.md	960
xaml/canvas-layout-guide.md	790
xaml/xaml-basics-and-rules.md	776
xaml/common-pitfalls.md	767
coded/operations-guide.md	677
ui-automation-guide.md	574
legacy/testing-guide.md	552
environment-setup.md	502
cli-reference.md	500
legacy/selector-guide.md	488
is-connector-xaml-guide.md	464
coded/codedworkflow-reference.md	431
assets/codedworkflow-template.md	415
uia-configure-target-workflows.md	287
library-authoring-guide.md	263
xaml/csharp-activity-binding-guide.md	162

Content absorption is correct across all files. The byte-identical 34-line duplicated section in common-pitfalls.md was properly removed. NGetText skip-tax now stated once (was 4×). Deduplication in testing-guide.md, debugging.md, and is-connector-xaml-guide.md all clean.

3. references/legacy/cli-reference.md:784-803, 941-960 — duplicate troubleshooting

Severity: Medium

Two absorbed files both contained the same 5-item troubleshooting list:

• Lines 784-803: ### Troubleshooting (from discovery-workflow.md — condensed)
• Lines 941-960: ### Common Error Scenarios (from validation-and-fixing.md — slightly more detailed)

One should be removed. The more detailed version at 941-960 is the better survivor.

Fix this →

4. references/coded/operations-guide.md:545-556 — empty heading + duplicate API Discovery

Severity: Medium

The absorption of coding-guidelines.md introduced two issues:

• Line 545: ### Best Practices is an empty heading with no content before the next heading. The original coding-guidelines.md had ## Best Practices as a parent with ### API Discovery as child; when demoted one level, both landed at ###, leaving Best Practices empty.
• Line 547-556: ### API Discovery is a condensed version of the full ## API Discovery (Before Creating Workflows) at line 288 — content overlap.

Fix: either remove ### Best Practices and the duplicate ### API Discovery (lines 545-556) entirely since line 288 covers it in full, or demote the API Discovery sub-items to #### and trim to a back-reference.

Fix this →

5. references/coded/operations-guide.md:590 — stale merge artifact

Severity: Medium

Line 590 contains @../validation-guide.md — a bare text reference (not a markdown link) carried over from the absorbed coding-guidelines.md. The target validation-guide.md was deleted in this PR. Should be removed or converted to a link to cli-reference.md § Validation Iteration Loop.

Fix this →

6. xaml/csharp-activity-binding-guide.md:128,141,145 — heading hierarchy

Severity: Low

Three ## headings should be ### to nest under the ## C# Expression Pitfalls parent at line 124. The original csharp-expression-pitfalls.md used ## as top-level; when absorbed under a new ## C# Expression Pitfalls parent, the sub-headings weren't demoted.

• Line 128: ## Attribute-form expressions fail at runtime → ###
• Line 141: ## `OutArgument<T>` attribute form fails at parse time → ###
• Line 145: ## ThrowIfNotInTree at runtime — two causes → ###

Fix this →

7. assets/codedworkflow-template.md — stale code comment references (pre-existing)

Severity: Low

Ten in-code comments say // Add service-specific usings as needed — see references/coding-guidelines.md. The path was already wrong before this PR (missing coded/ subdirectory). The header-level markdown link at line 5 was correctly updated to operations-guide.md § Coding Guidelines, but the in-code comments were not.

Fix this →

8. xaml/canvas-layout-guide.md:143-145 — double horizontal rule

Severity: Low

Two consecutive --- from merge boundary (new section ends with ---, old content started with ---). Cosmetic only; remove one.

Fix this →

9. Cross-skill touch: skills/uipath-test/references/publish-and-link-guide.md

Severity: OK

Single line retargeted from publishing-guide.md (deleted) to cli-reference.md#pack--publish-to-orchestrator. Anchor resolves. Pre-existing cross-skill reference pattern preserved.

10. Fixes bundled in this PR

Severity: OK (all improvements)

• Personal path C:\Users\alexandru.roman\... removed from _REFRAMEWORK.md and _DU-PROCESS.md — confirmed clean.
• Cross-skill file links in coded/integration-service-guide.md properly converted to inline CLI commands with graceful delegation text.
• Unclosed code fence in integration-service-guide.md:260 fixed.
• testing-guide.md properly deduplicated (Test Manager commands → pointer, JSON block → pointer).
• docs/uipath-rpa-v2.md — well-structured plan document, appropriate for docs/.

What's Missing

Nothing blocking. The three Medium findings are small mechanical fixes (remove duplicate section, remove empty heading + duplicate content, fix stale artifact). The three Low findings are polish.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Untouched — valid name, description under 1024 chars
E2E Tests	OK	No new capabilities; existing tests unaffected
Skill Body	OK	All 30+ SKILL.md anchor retargets verified
References & Assets	Minor Issues	3 Medium (duplicates, stale artifact) + 3 Low (heading hierarchy, comments, formatting)
Repo Hygiene	OK	Scoped changes, CODEOWNERS covers path, no secrets

Issues for Manual Review

• Merge conflict with PR feat(uipath-rpa): execution maps + pattern card — cut greenfield builds from ~36-40 to ≤10 turns #1827 (feat/uipath-rpa-execution-maps): documented, whichever lands second rebases.
• Three files 3–6% over the soft ~12k token cap: justified tradeoff (one fewer Read per flow); splitting back would re-add turns.
• A/B comparison (/skill-compare): recommended before merge to confirm the hypothesis that merged references reduce turns without reducing success rate.

Conclusion

High-quality mechanical refactoring PR with thorough link retargeting. Three Medium findings should be fixed before merge — all are small: (1) duplicate troubleshooting in legacy/cli-reference.md, (2) empty heading + duplicate API Discovery in coded/operations-guide.md, (3) stale @../validation-guide.md artifact. Three Low findings are nice-to-fix. Recommend approval after the Medium fixes.

---

|