@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-review/references/architecture-assessment-guide.md

@@ -1,159 +1,147 @@
 # Architecture Assessment Guide
 
-Architecture-level evaluation framework for UiPath automation solutions. Use during Step 4 (Optimization) of the review workflow to assess whether the right approach, architecture, and operational practices were chosen.
+Architecture-level evaluation framework for UiPath automation solutions during Step 4 (Optimization). Evaluate design decisions, not implementation quality; use type-specific checklists for implementation review.
 
-> This guide evaluates **design decisions**, not implementation quality. Use the type-specific checklists (RPA, agent, flow) for implementation-level review.
+## 1. Process Suitability
 
-## 1. Process Suitability Assessment
+Determine whether automation and the selected automation type are appropriate.
 
-Before evaluating how well the automation is built, assess whether automation was the right choice and whether the right type of automation was chosen.
-
-### Suitability Criteria
-
-| Criterion | Favorable for Automation | Unfavorable | How to Assess |
+| Criterion | Favorable | Unfavorable | Assess by |
 |---|---|---|---|
-| Rule-based | Process follows clear, documented rules | Requires human judgment or intuition | Read PDD or infer from workflow logic |
+| Rule-based | Clear, documented rules | Human judgment or intuition required | Read PDD or infer from workflow logic |
 | High volume | >50 transactions/day OR high frequency | <5 transactions/week | Ask user or check queue volume data |
-| Stable interfaces | Applications rarely change UI/API | Frequent UI redesigns or API changes | Ask user about application change frequency |
-| Digital input | Data available in digital format | Handwritten, verbal, or physical inputs | Check input sources in workflow |
-| Low exception rate | >80% of cases follow the standard path | >50% require human intervention | Check exception handling complexity |
-| Measurable | Clear metrics to quantify ROI | Benefits are intangible or hard to measure | Check for KPI tracking in solution |
-
-### Suitability Findings
+| Stable interfaces | Applications rarely change UI/API | Frequent UI redesigns or API changes | Ask about application change frequency |
+| Digital input | Digital data | Handwritten, verbal, or physical input | Check workflow input sources |
+| Low exception rate | >80% follow the standard path | >50% require human intervention | Check exception-handling complexity |
+| Measurable | Clear ROI metrics | Benefits are intangible or difficult to measure | Check KPI tracking |
 
-| Assessment Result | Severity | Recommendation |
+| Finding | Severity | Recommendation |
 |---|---|---|
-| Process is not rule-based and uses RPA (not agent) | Warning | Consider agent-based or hybrid approach |
-| Volume is very low (<5/week) with complex automation | Info | ROI may not justify automation complexity |
-| Application interfaces change frequently | Warning | Design for resilience: Object Repository, anchor-based selectors, healing |
-| Input is not digital and no DU pipeline | Warning | Add Document Understanding pipeline or consider manual step |
-| Exception rate >50% | Warning | Reconsider automation scope or add human-in-the-loop |
-| No metrics or monitoring in place | Info | Add KPI tracking for ROI justification |
+| Process is not rule-based and uses RPA (not agent) | Warning | Consider an agent-based or hybrid approach |
+| Volume is very low (<5/week) with complex automation | Info | Assess whether ROI justifies complexity |
+| Interfaces change frequently | Warning | Use resilience measures such as Object Repository, anchor-based selectors, and healing |
+| Input is not digital and no DU pipeline exists | Warning | Add a Document Understanding pipeline or consider a manual step |
+| Exception rate >50% | Warning | Reconsider scope or add human-in-the-loop handling |
+| No metrics or monitoring | Info | Add KPI tracking to justify ROI |
 
 ## 2. Complexity Classification
 
-Classify the solution's complexity to set appropriate review expectations.
-
-| Level | Criteria | Architecture Expectations |
+| Level | Criteria | Architecture expectations |
 |---|---|---|
-| **Simple** | Single application, linear flow, <10 steps, structured data | Single workflow or simple sequence. REFramework optional. Basic error handling. |
-| **Medium** | 2-3 applications, branching logic, data transformations, 10-30 steps | REFramework or equivalent. Config.xlsx. Proper error handling. Sub-workflows. |
-| **Complex** | Multiple applications, many exception paths, queues, unstructured data, business rules | Dispatcher-Performer. REFramework mandatory. Library extraction. Comprehensive testing. |
-| **Advanced** | Multi-actor (RPA + agents + humans), long-running, cross-system orchestration, AI/ML | Maestro/Flow orchestration. Agents for reasoning. Evaluation sets. Full CI/CD. |
-
-### Complexity Mismatch Findings
+| **Simple** | Single application, linear flow, <10 steps, structured data | Single workflow or simple sequence; REFramework optional; basic error handling |
+| **Medium** | 2-3 applications, branching, data transformations, 10-30 steps | REFramework or equivalent; Config.xlsx; proper error handling; sub-workflows |
+| **Complex** | Multiple applications, many exception paths, queues, unstructured data, business rules | Dispatcher-Performer; REFramework mandatory; library extraction; comprehensive testing |
+| **Advanced** | RPA + agents + humans, long-running, cross-system orchestration, AI/ML | Maestro/Flow orchestration; agents for reasoning; evaluation sets; full CI/CD |
 
 | Mismatch | Severity | Recommendation |
 |---|---|---|
-| Simple process with Complex architecture (over-engineered) | Info | Simplify — remove unnecessary REFramework, queues, or libraries |
-| Complex process with Simple architecture (under-engineered) | Warning | Add REFramework, proper error handling, config management |
-| Advanced process without orchestration layer (Flow/Maestro) | Warning | Add orchestration for multi-actor coordination |
-| Agent used for Simple deterministic task | Info | Replace with RPA for cost efficiency and determinism |
-| RPA used for Advanced reasoning task | Warning | Replace with agent or hybrid approach |
+| Simple process with complex architecture | Info | Remove unnecessary REFramework, queues, or libraries |
+| Complex process with simple architecture | Warning | Add REFramework, proper error handling, and configuration management |
+| Advanced process without Flow/Maestro orchestration | Warning | Add orchestration for multi-actor coordination |
+| Agent used for a simple deterministic task | Info | Replace with RPA for cost efficiency and determinism |
+| RPA used for an advanced reasoning task | Warning | Replace with an agent or hybrid approach |
 
 ### Process Mining as Suitability Input
 
-If Process Mining or Task Mining data is available, use it to inform the suitability assessment:
+When Process Mining or Task Mining data exists, use it in the suitability assessment.
 
-| Data Source | What It Tells You | Review Action |
+| Data source | Indicates | Review action |
 |---|---|---|
-| Process Mining event logs | Actual process flow, variants, bottlenecks, rework loops | Verify the automation matches the actual process (not just the documented ideal) |
-| Task Mining recordings | Step-by-step desktop actions, time per step, variation across users | Verify automation covers the most common task variant first |
-| Variant analysis | How many different paths exist in the real process | High variation (>10 common variants) = higher complexity classification |
-| Automation scoring | Volume × rule-based-ness × stability | Verify scored candidates match the solution's target processes |
-| Baseline metrics | Current cycle time, error rate, throughput | Use as benchmark for post-automation comparison |
+| Process Mining event logs | Actual flow, variants, bottlenecks, and rework loops | Verify that automation matches the actual process, not only the documented ideal |
+| Task Mining recordings | Desktop actions, time per step, and user variation | Verify coverage of the most common task variant first |
+| Variant analysis | Number of real process paths | Treat high variation (>10 common variants) as higher complexity |
+| Automation scoring | Volume × rule-based-ness × stability | Verify scored candidates match the targeted processes |
+| Baseline metrics | Current cycle time, error rate, and throughput | Use for post-automation comparison |
 
-| Check | Severity | How to Verify |
+| Check | Severity | Verify by |
 |---|---|---|
-| Process Mining data was used to validate automation scope (if available) | Info | Ask if mining was performed during discovery |
-| Baseline metrics recorded before automation (cycle time, error rate) | Info | Check for pre-automation measurement |
-| Automation targets the highest-volume, lowest-variation process paths | Info | Compare automation scope to mining variant analysis |
+| Process Mining data validated scope, if available | Info | Ask whether mining was performed during discovery |
+| Baseline metrics were recorded before automation | Info | Check for pre-automation measurement |
+| Automation targets highest-volume, lowest-variation paths | Info | Compare scope with mining variant analysis |
 
-## 3. Environment Separation Review
+## 3. Environment Separation
 
-Verify that the solution has proper environment isolation for safe deployment.
+Verify isolation for safe deployment.
 
 ### Environment Existence
 
-| Check | Severity | How to Verify |
+| Check | Severity | Verify by |
 |---|---|---|
-| Separate environments exist: Development, Test/QA, UAT, Production | Warning | Ask user or check Orchestrator folder structure |
+| Separate Development, Test/QA, UAT, and Production environments exist | Warning | Ask or check Orchestrator folder structure |
 | Each environment has its own Orchestrator folder | Warning | Check folder configuration |
-| Configuration differs per environment (URLs, paths, credentials) | Warning | Check config.json or asset management |
-| Deployment follows a promotion path (Dev → Test → UAT → Prod) | Info | Ask user about deployment process |
+| Configuration differs by environment (URLs, paths, credentials) | Warning | Check config.json or asset management |
+| Deployment follows Dev → Test → UAT → Prod | Info | Ask about deployment process |
 
 ### Configuration Isolation
 
-| Check | Severity | How to Verify |
+| Check | Severity | Verify by |
 |---|---|---|
-| No production URLs or paths in development code | Warning | Grep for production domain names in project files |
-| Credentials are environment-specific (not shared across environments) | Critical | Check credential asset configuration |
-| Queue names differ per environment OR use folder isolation | Warning | Check queue naming or folder strategy |
-| Assets are folder-scoped (not global) for environment isolation | Warning | Check asset folder assignments |
+| No production URLs or paths are in development code | Warning | Grep project files for production domain names |
+| Credentials are environment-specific, not shared | Critical | Check credential asset configuration |
+| Queue names differ by environment OR folder isolation is used | Warning | Check queue naming or folder strategy |
+| Assets are folder-scoped, not global | Warning | Check asset folder assignments |
 | Config.json or solution configuration supports environment overrides | Info | Check configuration structure |
 
 ### Deployment Safety
 
-| Check | Severity | How to Verify |
+| Check | Severity | Verify by |
 |---|---|---|
-| Rollback plan documented (how to revert to previous version) | Info | Check documentation or deployment procedures |
-| Version pinning used in production (not "latest") | Warning | Check process version configuration |
-| CI/CD pipeline enforces tests before production deployment | Info | Check pipeline configuration |
-| Change approval process exists for production deployments | Info | Ask user about governance |
+| Rollback plan documents how to revert to the previous version | Info | Check documentation or deployment procedures |
+| Production uses version pinning, not "latest" | Warning | Check process version configuration |
+| CI/CD enforces tests before production deployment | Info | Check pipeline configuration |
+| Production change approval exists | Info | Ask about governance |
 
 ## 4. Architecture Principles Scoring
 
-Score each principle on a 1-5 scale. Report scores in the review.
-
-> Score these six principles for any project type to inform the optimization review (Step 4). They do **not** feed the agent letter grade — that is computed from finding counts in [agent-grading-rubric.md](agents/agent-grading-rubric.md). Exclude a principle only when it genuinely does not apply (e.g. queue-style Scalability for a single agent) and state the exclusion.
+Score each applicable principle from 1-5 and report the scores. These six principles inform Step 4 and do **not** feed the agent letter grade, which is computed from finding counts in [agent-grading-rubric.md](agents/agent-grading-rubric.md). Exclude a principle only when it genuinely does not apply (for example, queue-style Scalability for a single agent), and state the exclusion.
 
 ### Modularity (1-5)
 
 | Score | Criteria |
 |---|---|
 | 1 | Monolithic: all logic in one workflow, no separation of concerns |
-| 2 | Some separation: Main.xaml delegates a few tasks, but workflows are still large |
-| 3 | Adequate: workflows have clear responsibilities, some reuse |
+| 2 | Some separation: Main.xaml delegates a few tasks, but workflows remain large |
+| 3 | Adequate: clear workflow responsibilities and some reuse |
 | 4 | Good: clean separation, libraries for shared logic, testable components |
 | 5 | Excellent: fully modular, library-based, independently testable, documented interfaces |
 
-**How to assess:** Count workflows, check responsibilities, look for library usage, check for duplicated logic.
+Assess by counting workflows and checking responsibilities, library usage, and duplicated logic.
 
 ### Scalability (1-5)
 
 | Score | Criteria |
 |---|---|
-| 1 | Sequential processing, no queue support, single robot only |
-| 2 | Sequential but could support multiple robots with minor changes |
-| 3 | Queue-based processing OR supports multiple robots |
-| 4 | Dispatcher-Performer with queue, supports horizontal scaling |
-| 5 | Elastic scaling, cloud robots, load-balanced queue processing, performance-optimized |
+| 1 | Sequential processing, no queue support, single robot |
+| 2 | Sequential, but multiple robots could be supported with minor changes |
+| 3 | Queue-based processing OR multiple-robot support |
+| 4 | Dispatcher-Performer with queue and horizontal scaling |
+| 5 | Elastic scaling, cloud robots, load-balanced queue processing, performance optimization |
 
-**How to assess:** Check for queue usage, Dispatcher-Performer pattern, robot configuration, batch processing.
+Assess queue usage, Dispatcher-Performer design, robot configuration, and batch processing.
 
 ### Resilience (1-5)
 
 | Score | Criteria |
 |---|---|
-| 1 | No error handling, no retry logic, crashes on first failure |
-| 2 | Basic Try-Catch, but no retry, no transaction recovery |
-| 3 | REFramework or equivalent retry logic, basic exception handling |
-| 4 | Proper Business/System exception distinction, circuit breaker, recovery procedures |
-| 5 | Full resilience: retry with backoff, circuit breaker, graceful degradation, self-healing selectors |
+| 1 | No error handling or retry; crashes on first failure |
+| 2 | Basic Try-Catch without retry or transaction recovery |
+| 3 | REFramework or equivalent retry logic and basic exception handling |
+| 4 | Business/System exception distinction, circuit breaker, and recovery procedures |
+| 5 | Retry with backoff, circuit breaker, graceful degradation, and self-healing selectors |
 
-**How to assess:** Check exception handling, retry configuration, REFramework compliance, recovery workflows.
+Assess exception handling, retry configuration, REFramework compliance, and recovery workflows.
 
 ### Maintainability (1-5)
 
 | Score | Criteria |
 |---|---|
-| 1 | No naming conventions, no documentation, no version control |
-| 2 | Some naming conventions, minimal documentation |
-| 3 | Consistent naming, Config.xlsx, basic documentation, version control |
-| 4 | Clean code, well-documented, tested, easy to onboard new developers |
-| 5 | Fully documented, comprehensive tests, CI/CD, code review process, activity annotations |
+| 1 | No naming conventions, documentation, or version control |
+| 2 | Some naming conventions and minimal documentation |
+| 3 | Consistent naming, Config.xlsx, basic documentation, and version control |
+| 4 | Clean, documented, tested code that is easy to onboard developers to |
+| 5 | Full documentation, comprehensive tests, CI/CD, code review, and activity annotations |
 
-**How to assess:** Check naming conventions, Config.xlsx usage, test coverage, documentation, git history.
+Assess naming conventions, Config.xlsx usage, test coverage, documentation, and git history.
 
 ### Security (1-5)
 
@@ -161,34 +149,34 @@ Score each principle on a 1-5 scale. Report scores in the review.
 |---|---|
 | 1 | Hardcoded credentials, plaintext passwords, no access control |
 | 2 | Some credentials in assets, but inconsistent |
-| 3 | All credentials in Orchestrator assets, SecureString used |
+| 3 | All credentials in Orchestrator assets; SecureString used |
 | 4 | External credential store, least-privilege robot accounts, no PII in logs |
-| 5 | Full security: vault integration, encrypted queues, audit trails, PII masking, compliance-ready |
+| 5 | Vault integration, encrypted queues, audit trails, PII masking, compliance readiness |
 
-**How to assess:** Check credential storage, SecureString usage, log content, queue encryption, access controls.
+Assess credential storage, SecureString usage, log content, queue encryption, and access controls.
 
 ### Governance (1-5)
 
 | Score | Criteria |
 |---|---|
-| 1 | No process documentation, no monitoring, no approval workflow |
-| 2 | Basic PDD exists, some monitoring |
-| 3 | PDD and SDD, Orchestrator monitoring, change management |
-| 4 | CoE standards followed, Automation Ops policies, CI/CD pipeline |
-| 5 | Full governance: CoE oversight, approval workflows, audit compliance, automation inventory, KPI tracking |
+| 1 | No process documentation, monitoring, or approval workflow |
+| 2 | Basic PDD and some monitoring |
+| 3 | PDD and SDD, Orchestrator monitoring, and change management |
+| 4 | CoE standards, Automation Ops policies, and CI/CD pipeline |
+| 5 | CoE oversight, approval workflows, audit compliance, automation inventory, and KPI tracking |
 
-**How to assess:** Check documentation, monitoring dashboards, Automation Ops policies, deployment procedures.
+Assess documentation, monitoring dashboards, Automation Ops policies, deployment procedures, and governance controls.
 
-## 5. Non-REFramework State Machine Assessment
+## 5. Non-REFramework State Machines
 
-For projects using State Machine layout outside of REFramework:
+For State Machine layouts outside REFramework, verify:
 
-| Check | Severity | How to Verify |
+| Check | Severity | Verify by |
 |---|---|---|
-| Each state has a single, clear responsibility | Warning | Read state names and entry actions |
-| All states have at least one outgoing transition | Critical | Check for dead-end states |
-| Default transition defined for each state (prevents runtime hangs) | Warning | Check for unhandled transition conditions |
-| No infinite cycles without exit conditions | Critical | Trace state transitions — verify every cycle has an exit |
-| Entry and exit actions are lightweight (heavy logic in transitions or sub-workflows) | Info | Check entry/exit action complexity |
-| State names are descriptive (not "State1", "State2") | Info | Review state naming |
+| Each state has one clear responsibility | Warning | Read state names and entry actions |
+| Every state has at least one outgoing transition | Critical | Check for dead-end states |
+| Each state has a default transition | Warning | Check for unhandled conditions that could cause runtime hangs |
+| No infinite cycle lacks an exit condition | Critical | Trace transitions and verify every cycle exits |
+| Entry and exit actions are lightweight | Info | Check that heavy logic is in transitions or sub-workflows |
+| State names are descriptive, not "State1" or "State2" | Info | Review state naming |
 | Final State is reachable from every state through some transition path | Critical | Trace reachability to Final State |

package/skills/uipath-review/references/review-workflow-guide.md

@@ -306,7 +306,7 @@ Use when the issue is a **missed optimization** or **minor convention deviation*
 
 ## Report Format Specification
 
-The review report follows a fixed markdown structure. Produce it in chat — do NOT write it to a file.
+The review report follows a fixed markdown structure. Produce it in chat; **and when the task asks you to save it to a path (e.g. `./_review_report.md`), also write it to that exact path.** The read-only rule forbids creating or editing files **inside the project under review** — it does NOT forbid writing the requested report file.
 
 ```markdown
 ## Review Report: <Solution/Project Name>

package/skills/uipath-review/references/rpa/modern-studio-issues.md

@@ -1,86 +1,86 @@
 # Modern Studio / 2024.10+ Specific Issues
 
-Antipatterns specific to UiPath Studio 2024.10+ (Modern design experience, coded workflows, Object Repository, Data Manager, Healing Agent).
+Antipatterns for UiPath Studio 2024.10+ Modern design experience, coded workflows, Object Repository, Data Manager, and Healing Agent.
 
 ## Modern Excel + Classic Excel Mixing
 
-**Symptom:** Same project contains both `UseExcelFile` (Modern — uses ClosedXML, no Excel needed) and `ExcelApplicationScope` (Classic — requires Excel installed, uses COM), OR `WriteRangeWorkbook` / `ReadRangeWorkbook` (Workbook activities) nested inside a `UseExcelFile` scope.
+**Symptom:** A project contains both `UseExcelFile` (Modern; ClosedXML; no Excel required) and `ExcelApplicationScope` (Classic; requires Excel; COM), or contains `WriteRangeWorkbook` / `ReadRangeWorkbook` inside `UseExcelFile`.
 
-**Impact:** COM object conflicts. Workbook activities and `Use Excel File` fight for the same file handle. Intermittent file lock errors, data corruption, Excel processes left behind in memory.
+**Impact:** COM conflicts, file locks, corruption, and orphaned Excel processes.
 
-**Detection:** Grep `.xaml` for both `ExcelApplicationScope` and `ExcelApplicationCard` (UseExcelFile) in the same project. Grep for `WriteRangeWorkbook` / `ReadRangeWorkbook` activities appearing as children of `ExcelApplicationCard`.
+**Detection:** Grep `.xaml` for both `ExcelApplicationScope` and `ExcelApplicationCard`. Grep for `WriteRangeWorkbook` / `ReadRangeWorkbook` as children of `ExcelApplicationCard`.
 
-**Fix:** Pick one approach per project. For new work, use Modern (`Use Excel File`) for workflows that don't need macros/pivots. Use Classic `Excel Application Scope` when you need Excel-specific features (macros, pivots, charts).
+**Fix:** Choose one approach per project. Use Modern `Use Excel File` for new workflows that do not need macros or pivots; use Classic `Excel Application Scope` for macros, pivots, or charts.
 
 **Severity:** Warning
 
 ## Multiple Single Excel Process Scope Activities
 
-**Symptom:** Project contains more than one `Single Excel Process Scope` activity across its workflows.
+**Symptom:** More than one `Single Excel Process Scope` exists across project workflows.
 
-**Impact:** COM object error at runtime. This activity manages a single Excel COM instance — multiple scopes conflict.
+**Impact:** Multiple scopes conflict over the single Excel COM instance and cause runtime COM errors.
 
-**Detection:** Grep all `.xaml` files for `SingleExcelProcessScope`. Flag if count > 1 across the project.
+**Detection:** Grep all `.xaml` files for `SingleExcelProcessScope`; flag counts above one across the project.
 
-**Fix:** Consolidate to one `Single Excel Process Scope` per project. If multiple isolated Excel sessions are genuinely required, use separate workflows invoked sequentially.
+**Fix:** Use one `Single Excel Process Scope` per project. If isolated Excel sessions are genuinely required, use separate workflows invoked sequentially.
 
 **Severity:** Critical
 
 ## Modern Excel Read Range Performance Cliff
 
-**Symptom:** Using Modern `Use Excel File` + `Read Range` for large datasets (>10K rows) without mitigation.
+**Symptom:** Modern `Use Excel File` + `Read Range` reads datasets over 10K rows without mitigation.
 
-**Impact:** Orders of magnitude slower than Classic `Excel Application Scope` + `Read Range` on large sheets — community reports range from minutes to tens of minutes for 10K+ rows. Affects SAP-exported data with special characters / images especially badly.
+**Impact:** Large reads can be orders of magnitude slower than Classic `Excel Application Scope` + `Read Range`, with reports ranging from minutes to tens of minutes for 10K+ rows. SAP-exported data with special characters or images can be especially affected.
 
-**Detection:** Project uses Modern design + `Use Excel File` + `Read Range` on datasets known to exceed 10K rows. `ReadOnly` property not set.
+**Detection:** Confirm Modern design, `Use Excel File`, `Read Range`, a dataset known to exceed 10K rows, and an unset `ReadOnly` property.
 
-**Fix:** For large read-only reads, use Classic `Excel Application Scope`. If staying on Modern, set `ReadOnly = True` and read specific ranges rather than whole sheets. For very large data, consider DataTable operations with CSV intermediate storage.
+**Fix:** For large read-only reads, use Classic `Excel Application Scope`. If remaining on Modern, set `ReadOnly = True` and read specific ranges instead of whole sheets. For very large data, consider DataTable operations with CSV intermediate storage.
 
 **Severity:** Warning
 
 ## Wrong Project Compatibility for Target Runtime
 
-**Symptom:** Project's `targetFramework` in `project.json` does not match the deployment target — e.g., `Windows` targeting Linux serverless robots, or `Portable` (cross-platform) project using UI Automation activities.
+**Symptom:** `project.json` `targetFramework` does not match deployment, such as `Windows` for Linux/container-based serverless robots or `Portable` for projects using UI Automation activities.
 
-**Impact:** Windows projects fail immediately on Linux with unclear errors. Cross-platform projects lack entire activity categories (UI Automation, Excel interop). The compatibility choice is set at creation and cannot be changed — only recreated.
+**Impact:** Windows projects fail on Linux; cross-platform projects lack UI Automation and Excel COM activity categories. Compatibility is set at creation and cannot be changed; the project must be recreated.
 
-**Detection:** Read `project.json` `targetFramework`. Cross-check against deployment target: if `Windows` and any deployment target is Linux/container-based, flag. If `Portable` and project contains UI Automation or Excel COM activities, flag.
+**Detection:** Read `project.json` `targetFramework` and compare it with deployment. Flag `Windows` for Linux/container-based deployment and `Portable` when UI Automation or Excel COM activities are present.
 
-**Fix:** Recreate the project with correct compatibility for the deployment target. Migrate source files manually (no automated converter between Windows and Cross-platform).
+**Fix:** Recreate the project with the correct compatibility and migrate source files manually; no automated converter exists between Windows and Cross-platform.
 
 **Severity:** Critical
 
 ## Project Rename Breaks Coded Workflow Assembly References
 
-**Symptom:** Project renamed after `.cs` coded workflows or Coded Source Files have been created.
+**Symptom:** A project is renamed after `.cs` coded workflows or Coded Source Files are created.
 
-**Impact:** Assembly references in XAML files become stale. Coded types unresolvable. Compiles locally (cached) but fails during clean build, publishing, or cross-project invocation.
+**Impact:** XAML assembly references become stale and coded types become unresolvable. Cached local builds may succeed while clean builds, publishing, or cross-project invocation fails.
 
-**Detection:** Grep XAML for `AssemblyQualifiedName` or `clr-namespace=...;assembly=` references. Compare the assembly name to `project.json` `name` field.
+**Detection:** Grep XAML for `AssemblyQualifiedName` or `clr-namespace=...;assembly=` and compare the assembly name with `project.json` `name`.
 
-**Fix:** Do not rename projects with coded workflows. If rename is required: clean the project, remove all `.cs.json` metadata, rebuild, and fix XAML references manually. Simpler: recreate the project and migrate source.
+**Fix:** Do not rename projects containing coded workflows. If required, clean the project, remove all `.cs.json` metadata, rebuild, and fix XAML references manually. Prefer recreating the project and migrating source.
 
 **Severity:** Critical
 
 ## Coded Workflow Arguments Without Parameterless Constructor
 
-**Symptom:** Custom data types used as coded workflow (`[Workflow]`) arguments without a public parameterless constructor.
+**Symptom:** A custom data type used as a coded workflow (`[Workflow]`) argument lacks a public parameterless constructor.
 
-**Impact:** Studio cannot serialize/deserialize arguments. Surfaces as Studio validation errors, inability to invoke the workflow, or runtime failures during argument marshaling.
+**Impact:** Studio cannot serialize or deserialize the argument, causing validation, invocation, or runtime argument-marshaling failures.
 
-**Detection:** Grep `.cs` files for classes used as workflow arguments. Check each for a `public ClassName()` constructor (no parameters).
+**Detection:** Grep `.cs` files for classes used as workflow arguments and check for `public ClassName()` constructors with no parameters.
 
-**Fix:** Add a public parameterless constructor to every class used as a workflow argument, or use built-in serializable types (primitives, DataTable, JObject).
+**Fix:** Add a public parameterless constructor to every such class, or use built-in serializable types such as primitives, `DataTable`, or `JObject`.
 
 **Severity:** Warning
 
 ## Coded / XAML Nested Class Argument Interop Failure
 
-**Symptom:** Hybrid project (both `.cs` and `.xaml`) passing arguments whose types are nested C# classes between coded and XAML workflows.
+**Symptom:** A hybrid `.cs`/`.xaml` project passes nested C# class types between coded and XAML workflows, including through `InvokeWorkflowFile` when the invoked workflow is a `.cs` file.
 
-**Impact:** XAML engine cannot resolve types from nested classes. Compiles locally but fails at runtime with `"Value cannot be null (Parameter 'type')"` or similar type-resolution errors. Documented Studio 2024.10+ limitation.
+**Impact:** The XAML engine cannot resolve nested-class types. Local compilation may succeed, but runtime fails with `Value cannot be null (Parameter 'type')` or similar type-resolution errors. This is a documented Studio 2024.10+ limitation.
 
-**Detection:** In hybrid projects, check `InvokeWorkflowFile` arguments where the invoked workflow is a `.cs` file. Verify argument types are not nested class definitions.
+**Detection:** In hybrid projects, inspect `InvokeWorkflowFile` arguments for invoked `.cs` workflows and verify that argument types are not nested class definitions.
 
 **Fix:** Flatten nested class hierarchies used as arguments. Use top-level public classes or Pydantic-style DTOs.
 
@@ -88,48 +88,48 @@ Antipatterns specific to UiPath Studio 2024.10+ (Modern design experience, coded
 
 ## Object Repository Flat Structure (No Application/Screen Hierarchy)
 
-**Symptom:** All UI descriptors dumped into `.objects/` without organizing into the Application → Screen → Element hierarchy. Duplicate descriptors for the same UI element created by different developers.
+**Symptom:** UI descriptors are dumped directly into `.objects/` without an Application → Screen → Element hierarchy, and different developers create duplicates for the same element.
 
-**Impact:** Unmaintainable descriptor soup. When target UI changes, no way to scope updates to one screen. Duplicate descriptors cause "which is authoritative?" confusion. Descriptor count grows linearly with team size.
+**Impact:** The repository becomes unmaintainable; UI changes cannot be scoped to a screen, authoritative descriptors are unclear, and descriptor count grows with team size.
 
-**Detection:** Inspect `.objects/` folder structure. Flat list of descriptors (no Application/Screen subfolders) = antipattern. Search for descriptors with overlapping selectors targeting the same UI element.
+**Detection:** Inspect `.objects/`. A flat descriptor list without Application/Screen subfolders is an antipattern. Search for overlapping selectors targeting the same UI element.
 
-**Fix:** Restructure using Application → Screen → Element hierarchy. Deduplicate — each distinct UI element gets one authoritative descriptor. Promote org-wide descriptors into a published UI Library.
+**Fix:** Organize descriptors as Application → Screen → Element. Deduplicate so each distinct UI element has one authoritative descriptor. Promote organization-wide descriptors into a published UI Library.
 
 **Severity:** Warning
 
 ## Data Manager Global Variable Naming Conflicts
 
-**Symptom:** Global variables created via Data Manager share names with arguments or local variables in sub-workflows.
+**Symptom:** A Data Manager global variable shares a name with an argument or local variable in a sub-workflow.
 
-**Impact:** Variables and arguments with the same name = variable takes precedence silently. Workflow uses the wrong value. Especially dangerous when globals are not supported in libraries / isolated invocations.
+**Impact:** The variable silently takes precedence, so the workflow may use the wrong value. This is especially dangerous when globals are unsupported in libraries or isolated invocations.
 
-**Detection:** Parse all XAML for variables scoped at Global. Check if any global name matches an argument name in any workflow.
+**Detection:** Parse all XAML for variables scoped at Global and compare global names with argument names in every workflow.
 
-**Fix:** Use distinct naming conventions for globals (e.g., `g_ConfigValue` prefix) vs arguments (`in_`, `out_`, `io_`). Rename to eliminate collisions.
+**Fix:** Use distinct conventions, such as `g_ConfigValue` for globals and `in_`, `out_`, or `io_` for arguments; rename collisions.
 
 **Severity:** Warning
 
 ## Healing Agent Noise Logs on Classic Activities
 
-**Symptom:** Project uses Classic UI activities (`Attach Window`, classic `FindElement`, classic `GetAttribute`) and Healing Agent is not explicitly disabled.
+**Symptom:** A project uses Classic UI activities (`Attach Window`, classic `FindElement`, classic `GetAttribute`, etc.) without explicitly disabling Healing Agent.
 
-**Impact:** Classic activities trigger Healing Agent telemetry logging ("Healing agent configuration") even when healing is not enabled. No suppression mechanism exists. Log noise clutters monitoring and masks real issues, especially at scale.
+**Impact:** Classic activities generate Healing Agent telemetry such as `Healing agent configuration` even when healing is not enabled. No suppression mechanism exists; noise can obscure real issues at scale.
 
-**Detection:** Grep XAML for Classic UI activity types (`AttachWindow`, classic `FindElement`, etc.). Check governance policy for Healing Agent disable setting.
+**Detection:** Grep XAML for Classic UI activity types such as `AttachWindow` and classic `FindElement`, then check governance policy for a Healing Agent disable setting.
 
-**Fix:** Either migrate Classic activities to Modern (which uses Healing Agent cleanly), OR explicitly disable Healing Agent for projects using Classic activities via governance policy.
+**Fix:** Migrate Classic activities to Modern, or explicitly disable Healing Agent through governance policy for projects using Classic activities.
 
 **Severity:** Info
 
 ## Object Repository in Project When UI Library Needed
 
-**Symptom:** Multiple projects in the org automate the same target application (e.g., SAP, Salesforce), each with its own local `.objects/` Object Repository for that app.
+**Symptom:** Multiple projects automate the same target application, each maintaining a local `.objects/` repository.
 
-**Impact:** UI changes require updating every project's local copy. Selector fixes don't propagate. Teams end up with divergent descriptors — "works on my project, fails on theirs." Healing Agent healing one project's copy doesn't help the others.
+**Impact:** UI changes require updates in every project, selector fixes do not propagate, and repositories diverge. Healing one project's copy does not help others.
 
-**Detection:** Find all projects referencing the same application in `.objects/`. Check `project.json` dependencies for a shared UI Library. Absence = antipattern.
+**Detection:** Find projects referencing the same application in `.objects/`. Check `project.json` dependencies for a shared UI Library; absence is an antipattern.
 
-**Fix:** Extract the shared Object Repository into a published UI Library. Consumers reference it via `project.json` dependencies with pinned versions.
+**Fix:** Extract the shared Object Repository into a published UI Library. Reference it from consumers through `project.json` dependencies with pinned versions.
 
 **Severity:** Warning