---
name: uipath-review
description: "UiPath read-only reviewer — audit structure, quality, best practices for RPA (.xaml/.cs), agents (.py/agent.json), flows (.flow), BPMN (.bpmn), coded apps, solutions (.uipx). Does NOT edit files. For building/editing→domain skills."
allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion
user-invocable: true
---

# UiPath Solution & Artifact Reviewer

Review UiPath solutions and individual artifacts for structural validity, quality, best practices, optimization, and correctness. Produces a structured review report with findings and recommendations.

## When to Use This Skill

- User asks to "review", "audit", "check quality of", or "evaluate" a UiPath project or solution
- User asks "is this solution good?" or "what can be improved?"
- User wants a pre-deployment quality gate check
- User wants to understand the business value and architecture of an existing solution
- User asks about best practices for a specific artifact type
- User has inherited a UiPath project and wants to understand its quality

## Critical Rules

1. **NEVER modify any files.** This skill is read-only. If fixes are needed, identify them in the report and tell the user which skill to use (uipath-rpa, uipath-agents, uipath-maestro-flow, uipath-coded-apps, uipath-platform, uipath-solution).
2. **ALWAYS run validation and Workflow Analyzer before manual review.** For RPA projects, run **both** `uip rpa validate` on every entry point AND `uip rpa build "<PROJECT_DIR>"` — `validate` catches structural / analyzer issues, `build` catches compile-time issues `validate` misses (unknown member names, invalid enum values, JIT failures). Run `uip agent validate` on agents, `uip maestro flow validate` on flows. Report every Error, Warning, and Info result from every command. A review without both `validate` AND `build` (for RPA) is incomplete and may ship broken member references.
3. **ALWAYS discover and classify before reviewing.** For solutions: classify every project before reviewing any individual one. For single projects: identify the project type and find the enclosing project directory before reviewing individual files.
4. **Report severity for every finding.** Use: **Critical** (blocks deployment), **Warning** (should fix), **Info** (improvement opportunity).
5. **Understand business context first.** Before evaluating optimization, ask or infer what the solution is trying to accomplish. A queue-based architecture is not "better" if the use case processes 5 items/day.
6. **Use `--output json`** on all CLI validation commands for programmatic parsing.
7. **Do not duplicate what validation commands catch.** Reference the validation output by rule ID and message — do not manually re-describe the same issue. But DO include every validation result (Error, Warning, Info) in the report.
8. **Cap the review at 30 minutes of analysis.** For very large solutions (10+ projects), provide a summary review with deep dives on the 3 highest-risk projects. Offer to review remaining projects if the user wants.
9. **Run the review CLI first, then apply the judgment catalog, for every agent encountered.** First run `uip agent review` (low-code) or `uip codedagent review` (coded) with `--output json` — it returns the deterministic findings (Step 2.5a). Then load the judgment catalog: `references/agents/agents-common-rules.md` plus the format-specific file (`agents-lowcode-rules.md` or `agents-coded-rules.md`); for the agent-builder coded layout (both `agent.json` and `main.py`), load all three and run both CLI commands. Future phases add catalogs for RPA, flows, coded apps.
10. **Rule findings are authoritative as emitted.** Carry review-CLI findings (`Data.Issues[]`) into the report verbatim — `RuleId`, `Severity`, `Description`, `File`, `SuggestedFix` unchanged. For the judgment catalog, use its `rule_id`, `severity`, `trigger`, and `suggested_fix` verbatim. Map severity to the report's bands: `error` → Critical, `warning` → Warning, `info` → Info. `judgment` severity rows default to Warning; the agent may escalate or de-escalate with reasoning logged in the finding's `description`. Do not re-rank otherwise.
11. **Report rules that could not be applied** (missing tooling, missing file, review CLI unavailable, `status: deferred`) in a dedicated "Rules Skipped" subsection of the report — never silently skip.
12. **Never invent `rule_id` values.** Every `rule_id` cited in the report MUST appear verbatim in EITHER a loaded judgment-catalog file (`references/agents/agents-*-rules.md`) OR the `uip agent review` / `uip codedagent review` JSON output. `rule_id` is a stable contract identifier — consumers grep for it, dashboards aggregate by it, audits trace it. An invented identifier looks authoritative but cannot be looked up, doesn't aggregate, and produces a different name for the same observation on the next run. If you observe a real issue covered by neither source, the finding is still valid — report it as a normal Critical / Warning / Info finding **without** a `rule_id` (no `` `RULE_ID` `` backtick token in the line). **Before emitting the report, scan every cited `rule_id` and confirm it appears verbatim in a loaded catalog file or the review-CLI output; demote any that don't to `rule_id`-less findings.**

## Review Workflow

### Step 0 — Discover, Scope, and Locate the PDD

#### 0a. Probe the Filesystem

Run this from the directory the user specified (or the current working directory):

```bash
# Discover solution files, project markers, and documentation
find . -maxdepth 3 \( -name "*.uipx" -o -name "project.json" -o -name "agent.json" -o -name "*.flow" -o -name "app.config.json" -o -name ".uipath" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) 2>/dev/null

# Search for PDD or design documents
find . -maxdepth 3 \( -name "*PDD*" -o -name "*pdd*" -o -name "*Process_Design*" -o -name "*process_design*" -o -name "*Process-Design*" -o -name "*ProcessDesign*" -o -name "*SDD*" -o -name "*Solution_Design*" -o -name "*design_document*" -o -name "*DesignDocument*" -o -name "*requirements*" -o -name "*specification*" \) 2>/dev/null
```

#### 0b. Locate the PDD (Process Design Document)

The PDD is the **source of truth** for the review. It defines what the automation should do, its business context, expected inputs/outputs, exception handling requirements, and success criteria. The review evaluates whether the implementation matches the PDD.

**Search for PDD in this order:**

1. **Check common locations:** `./docs/`, `./documentation/`, `./Design/`, project root
2. **Check common names:** `PDD.docx`, `PDD.pdf`, `PDD.md`, `Process_Design_Document.*`, `SDD.*`, `Solution_Design_Document.*`, `Requirements.*`
3. **Check AGENTS.md or README.md** at project root — may contain or reference the PDD
4. **Check project.json** `description` field or any metadata pointing to documentation

**If PDD is found:**
- Read it (supports .md, .pdf, .docx via appropriate tools)
- Extract the key review criteria: business process description, expected inputs/outputs, exception handling requirements, SLAs, transaction definitions, queue specifications, application list, credential requirements
- Use it as the **primary benchmark** for all subsequent review steps

**If PDD is NOT found:**

Use the `AskUserQuestion` tool to ask interactively:

```
Question: "I could not find a Process Design Document (PDD) in this project. Do you have one I can use as the source of truth for this review?"
Header: "PDD"
Options:
  1. Label: "Yes, I have a file"
     Description: "I'll provide a file path, URL, or Confluence/SharePoint link to the PDD, SDD, or requirements document"
  2. Label: "I'll paste the content"
     Description: "I'll copy/paste the PDD content (or key sections) directly into the chat"
  3. Label: "No, proceed without"
     Description: "Skip PDD alignment — review will cover technical quality and best practices only, not business logic verification"
```

- **If user selects "Yes, I have a file":** they will provide the path in their response. Read the document and proceed with PDD-informed review.
- **If user selects "I'll paste the content":** they will paste the PDD text (or relevant sections) in their next message. Use that content as the PDD for the review.
- **If user selects "No, proceed without":** proceed without it — the review will focus on technical quality, best practices, and structural correctness, but cannot verify business logic alignment. Note this limitation in the report.

#### 0c. Determine Review Scope

> **Workflow labels like "Path A / Path B / Step 3a" are internal to this skill. NEVER use them in the final review report.** The report must use user-facing language — see Step 5 for the required **Review Scope** vocabulary.

Classify the scope internally using these rules:

**Scope: Solution or Multi-project** — `.uipx` exists at root, OR 2+ **executable** project markers exist in different subdirectories.

- Executable project = `project.json` with `outputType` of `Process`/`Tests`/unspecified, OR `agent.json`, OR `.flow`
- Library projects (`outputType: "Library"`) co-located with consumers do NOT trigger this scope — that is the normal library+consumer pattern
- **Windows-Legacy executables do NOT trigger this scope for `.uipx` purposes**: `.uipx` solutions are not supported for Legacy projects. If any detected executable is Legacy, do not flag missing `.uipx` — recommend migration to Modern compatibility if solution bundling is desired. Review each Legacy project independently.

Steps for Solution / Multi-project scope:
1. Read the `.uipx` file (if present) to enumerate all projects
2. Scan subdirectories for project markers not listed in `.uipx` (orphan executables)
3. Classify each project using the detection table in Step 1
4. Run solution-level checks: missing config.json, version mismatches, cross-project dependencies, circular dependencies
5. Build a solution map: every project with its type, path, and relationship to others
6. Cross-reference with PDD (if available)
7. Read [references/solution-review-guide.md](references/solution-review-guide.md) for the full procedure
8. Proceed to Step 1 for each project individually

**Scope: Single Project** — one `project.json` / `agent.json` / `.flow` / coded-app marker at root, no `.uipx`, no executable siblings.

1. Classify the project using the detection table in Step 1
2. Cross-reference with PDD (if available)
3. Skip solution-level checks; go directly to Step 1

If the user pointed to a specific file (e.g., `Main.xaml`), walk up to the enclosing project directory and review the full project.

---

### Step 1 — Classify the Project Type and Capture Language

For **each** project discovered (one for single-project scope, multiple for solution/multi-project scope), determine its type AND capture its expression language.

**Step 1a — Read `expressionLanguage` from `project.json` for every RPA project.** This is mandatory. The value (`VisualBasic` or `CSharp`) affects everything downstream: expression syntax in If/Switch conditions, null checks, type checks (`TypeOf x Is T` in VB vs `x is T` in C#), string operations, LINQ syntax, and naming conventions. All subsequent inspection steps (especially Step 3a Unit of Work grep and expression-dependent checks) MUST adapt patterns to the project's language. Do not assume VB.

Record the language per project alongside the type (see solution table below).

**Step 1b — Determine project type** using the detection table:

| Filesystem Signal | Project Type | Review Checklist |
|---|---|---|
| `project.json` + `.cs` files with `[Workflow]` attributes | RPA (Coded) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
| `project.json` + `.xaml` workflow files | RPA (XAML) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
| `project.json` with `expressionLanguage: "VisualBasic"` and no/Legacy `targetFramework` | RPA (Windows-Legacy) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) §10. Also recommend the user invoke `uipath-rpa` (Legacy mode) for Legacy-specific deep validation. Legacy is supported indefinitely in Studio LTS — do NOT flag as Critical. |
| `project.json` + both `.cs` and `.xaml` | RPA (Hybrid) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
| `project.json` + `.xaml` + DU packages in dependencies (`UiPath.IntelligentOCR.Activities`, `UiPath.DocumentUnderstanding.ML.Activities`) | RPA + Document Understanding | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) + [du-review-checklist.md](references/document-understanding/du-review-checklist.md) |
| `agent.json` (no `main.py`) | Agent (Low-Code) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
| `main.py` + `langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json` / `uipath.json` | Agent (Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
| `agent.json` + `main.py` + `pyproject.toml` (agent-builder coded layout) | Agent (Low-Code + Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): all three — [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
| `*.flow` + `project.uiproj` with `"ProjectType": "Flow"` | Flow | [flow-review-checklist.md](references/flows/flow-review-checklist.md) |
| `.uipath/` directory or `app.config.json` | Coded App | [coded-app-review-checklist.md](references/coded-apps/coded-app-review-checklist.md) |

For **Solution / Multi-project scope**, record all projects in a table:

```markdown
| # | Project Path | Type | Language | Entry Points |
|---|---|---|---|---|
| 1 | ./InvoiceProcessor/ | RPA (XAML) | VisualBasic | Main.xaml, Helper.xaml |
| 2 | ./Dispatcher/ | RPA (Coded) | CSharp | Main.cs |
| 3 | ./ClassifierAgent/ | Agent (Coded) | Python | main.py |
| 4 | ./Orchestration.flow | Flow | — | — |
```

### Step 2 — Run Automated Validation and Workflow Analyzer

This step is **mandatory** and **non-negotiable**. You MUST run validation commands yourself (via Bash) before doing any manual review.

- **Solution / Multi-project scope:** Run validation on **every project** in the solution. For each RPA project, validate **every entry point file**.
- **Single Project scope:** Run validation on the single project. For RPA projects, validate **every entry point file**.

Report **all** results — Errors, Warnings, and Info — in the final review report.

#### 2a. RPA Projects — Validate Every Entry Point

1. Read `project.json` → extract the `entryPoints` array
2. For **each** entry point file, run validation yourself:

```bash
uip rpa validate --file-path "<ENTRY_FILE>" --project-dir "<PROJECT_DIR>" --output json
```

3. **Then run a project-level build** to catch what `validate` misses (unknown member names like `NGetText.Value`, invalid enum values like `Operator="StartsWith"`, member resolution / CacheMetadata failures, attribute-form C# expression JIT failures):

```bash
uip rpa build "<PROJECT_DIR>" --log-level Warn --output json
```

4. Collect **all** results from both commands — Errors, Warnings, and Info-level messages
5. If any entry point has `validate` errors **or** the project fails to `build`, the project is **not deployable**

> Do NOT validate only Main.xaml — validate every file listed in `entryPoints`. A project can have multiple entry points and errors in any of them block deployment.

> Do NOT report a clean review based on `validate` alone. `validate` is static analysis; it does not catch unknown member names or invalid enum values. A "0 errors" `validate` result with a failing `build` is a real bug that ships if the reviewer skips `build`.

#### 2b. RPA Projects — Run Workflow Analyzer

The Workflow Analyzer checks code quality rules (ST-NMG naming, ST-DBP design, ST-MRD maintainability, ST-USG usage, ST-SEC security, ST-REL reliability). Run it explicitly:

```bash
uip rpa analyze --project-dir "<PROJECT_DIR>" --output json
```

If `uip rpa analyze` is not available, `uip rpa validate` includes Workflow Analyzer results. Check the output for all rule violations:

- **Error-level violations** → report as **Critical** findings (e.g., ST-SEC-007 SecureString, ST-ANA-005 missing project.json)
- **Warning-level violations** → report as **Warning** findings (e.g., ST-DBP-003 empty Catch, ST-MRD-011 Write Line usage, ST-NMG-001 naming)
- **Info-level violations** → report as **Info** findings (e.g., ST-ANA-003 workflow count, ST-ANA-009 file activity stats)

> Every Workflow Analyzer violation must appear in the review report with its rule ID, affected file, and description. Do not silently skip any severity level.

#### 2c. Other Project Types

| Project Type | Validation Command | Report All Severities |
|---|---|---|
| Agent (Low-Code) | `uip agent validate ./path --output json` | Yes — errors, warnings, info |
| Flow | `uip maestro flow validate <ProjectName>.flow --output json` | Yes — schema errors, reference errors, warnings |
| Coded App | `uip codedapp pack dist --dry-run` | Yes — build errors, pack warnings |
| Solution | `uip solution pack <SolutionDir> <OutputDir> --output json` | Yes — per-project pack results |

#### 2d. Record All Results

For the review report, create a validation summary:

```markdown
### Validation Results

| Project | Command | Errors | Warnings | Info |
|---|---|---|---|---|
| InvoiceProcessor | uip rpa validate (Main.xaml) | 0 | 3 | 1 |
| InvoiceProcessor | uip rpa validate (Helper.cs) | 1 | 0 | 0 |
| InvoiceDispatcher | uip maestro flow validate | 0 | 0 | 0 |
| ClassifierAgent | uip agent validate | 0 | 1 | 0 |

#### Validation Details
- [E-001] InvoiceProcessor/Helper.cs: ST-SEC-007 — Password argument uses String instead of SecureString
- [W-001] InvoiceProcessor/Main.xaml: ST-MRD-011 — Write Line activity used (use Log Message instead)
- [W-002] InvoiceProcessor/Main.xaml: ST-DBP-003 — Empty Catch block in TryCatch_1
- [W-003] InvoiceProcessor/Main.xaml: ST-NMG-001 — Variable 'temp_val' does not match naming convention
- [I-001] InvoiceProcessor: ST-ANA-009 — 12 file activities detected
- [W-004] ClassifierAgent: Missing tool description for 'lookup_customer'
```

> The validation results section is **required** in every review report. A review without automated validation is incomplete.

### Step 2.5 — Run the Review CLI, then Apply the Judgment Catalog

After Step 2 validation and before manual checklist review, produce rule-ID-level findings in two passes: **first** the `uip agent review` / `uip codedagent review` CLI for the deterministic static checks, **then** the skill's judgment-only catalog for what code cannot decide reliably.

#### 2.5a — Run the review CLI first (deterministic findings)

Run the review command for the agent type, once, capturing JSON:

| Agent type | Command |
|---|---|
| Low-code (`agent.json`) | `uip agent review "<PROJECT_DIR>" --output json` |
| Coded (`main.py` + framework config) | `uip codedagent review "<PROJECT_DIR>" --output json` |
| Agent-builder coded layout (`agent.json` + `main.py`) | run **both** commands |

The CLI runs every deterministic static check — structural/schema, placeholder cross-refs, eval counts/diversity, secret & import regex, framework symbol existence, eval-run analysis, packaging/git hygiene — and returns them in rule format. Parse `Data.Issues[]`; each issue is `{RuleId, Category, Severity, Description, File, SuggestedFix}`. Carry each into the report **verbatim** — do not re-derive, rename, or re-rank. These rule IDs are authoritative as emitted by the CLI; they are **not** listed in the skill catalog.

#### 2.5b — Apply the judgment catalog (reasoning the CLI cannot do)

1. **Identify which catalog files apply** for the current project type:

| Signals present | Project type | Catalog files |
|---|---|---|
| `agent.json` AND no `main.py` AND no `pyproject.toml` | Agent (low-code) | `references/agents/agents-common-rules.md` + `references/agents/agents-lowcode-rules.md` |
| `pyproject.toml` + `main.py` + any of `langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json` | Agent (coded) | `references/agents/agents-common-rules.md` + `references/agents/agents-coded-rules.md` |
| `pyproject.toml` + `main.py` + `uipath.json[functions]` only (no framework config) | Agent (coded — Simple Function) | same as Agent (coded) |
| `agent.json` + `pyproject.toml` + `main.py` (agent-builder coded layout) | Agent (low-code + coded) | all three: common + lowcode + coded; tag each finding with its source file |
| `project.json` + `.xaml` / `.cs` | RPA | *(phase 2)* |
| `*.flow` | Flow | *(phase 2)* |
| `.uipath/` or `app.config.json` | Coded App | *(phase 2)* |

2. **Read each catalog file in full.** Every rule is judgment-form.
3. **Apply each rule's `detection_method`:** read the named source material (system prompt, tool descriptions, eval datapoints, schemas) and reason about it. Emit a finding when the criteria hold; log the reasoning in the finding's `description`.
4. **Track skipped rules** with their reason (`status: deferred`, missing optional file, review CLI unavailable). Never silently skip.
5. **Verify rule_id provenance.** Before merging, confirm each cited `rule_id` appears **verbatim** in EITHER a loaded catalog file OR the `uip agent review` / `uip codedagent review` JSON output. Any finding whose `rule_id` matches neither is **demoted** to a `rule_id`-less Critical / Warning / Info finding (the observation stays; the false citation goes). This enforces Critical Rule 12.
6. **Merge findings into the Step 5 report** under the "Rule Findings" subsection. Use the canonical line format:

   ```
   [<prefix><n>] `<rule_id>` — <file> — <description>. Fix: <suggested_fix>.
   ```

   where prefix is `C-D-` (Critical), `W-D-` (Warning), or `I-D-` (Info) per the severity mapping in [`references/rule-format.md`](references/rule-format.md).

See [`references/rule-catalog-workflow.md`](references/rule-catalog-workflow.md) for the full procedure including the CLI contract and determinism rules.

### Step 3 — Manual Quality Review

For **each** project (one for single-project, all for solution/multi-project), load the relevant checklist from `references/` based on the type classified in Step 1. Read project files, check patterns, evaluate design.

#### 3a. Unit of Work Discovery (mandatory, generic)

Every project has two units of work: what the **contract** declares one invocation represents, and what the **execution body** actually does. A mismatch is a Critical-to-Warning finding regardless of project type. Do not ask the user — derive both mechanically from the project.

**Step 3a.1 — Discover the declared unit of work** (per project type):

| Project type | Where the declared unit lives |
|---|---|
| RPA + queue | Queue item schema (`Data/*.json`, `JSON Schema/`, or the SpecificContent fields used by `Add Queue Item` / `Get Transaction Item`) |
| RPA without queue | `Main.xaml` input arguments |
| Flow | `.flow` file → `variables.globals` → entries with `direction: "in"` or `"inout"` |
| Agent (low-code) | `agent.json` → `inputSchema` |
| Agent (coded) | `Input` class in `main.py` (Pydantic `BaseModel`) |
| API workflow | Request schema defined in the workflow |
| Coded app | Entry point input schema in `operate.json` / `entry-points.json` |

**Step 3a.2 — Discover the actual unit of work** (core execution body):

Identify the core execution file (`ProcessTransaction.xaml`, `Process.xaml`, `Main.xaml`, `main.py`, flow body, API handler) then run these mechanical checks:

```bash
# Detect iteration inside the execution body
grep -n 'ForEach\|While' <EXECUTION_FILE>

# Detect external-effect activities (writes, API calls, queue pushes, workflow invocations)
grep -n 'HttpRequest\|Add Queue Item\|InvokeWorkflowFile\|Write Range\|Write Line\|SqlCommand' <EXECUTION_FILE>
```

For coded projects, look for `for` / `foreach` / `while` statements and external I/O calls.

**Step 3a.3 — Classify using this matrix:**

Classify the **Transaction Shape** using this matrix. Shape is a neutral description of the relationship between input and external effects — it is NOT a pass/fail verdict.

| Actual execution pattern | Transaction Shape |
|---|---|
| One invocation → one atomic external state change (one write, one submission, one workflow call) | **One-to-one** |
| Execution iterates over an array/collection field of the declared input, and the loop body contains external effects (see list below) | **One-to-many** |
| Iteration only over retry counters, UI element enumeration, or pure in-memory transformations (no external effects in loop body) | **One-to-one** (in-memory iteration is intra-unit; not a sub-unit of work) |
| No iteration at all | **One-to-one** |
| Contract or execution cannot be deterministically mapped (schema missing/unclear, dynamic dispatch) | **Unclear** |

**External effects inside a loop body that make it one-to-many** (none of these are defeated by session scope, shared credentials, single portal, or business-model arguments):

- `InvokeWorkflowFile` / `Invoke Method` to workflows with external side effects
- HTTP activities (`HTTP Request`, connector activities, REST calls)
- Queue operations (`Add Queue Item`, `Set Transaction Progress`, `Set Transaction Status`)
- Database writes (`Execute Non Query`, `Insert Data Table`, `Bulk Insert`)
- File writes outside `Temp/` directories (`Write Range`, `Write CSV`, `Append to File`)
- UI activities that modify target-system state (Click on submit/save, Type Into fields that persist, SAP `Call Transaction`)
- Email send activities

Classification is mechanical. It does not change based on:
- "The portal models this as one transaction" (UX framing ≠ atomicity)
- "One browser session" (session ≠ transaction)
- "Idempotency guards exist so it's fine" (guards are a remediation signal, not a reclassifier)
- "The PDD calls it one transaction" (declared intent ≠ execution reality)
- "The queue only has one item" (queue is the declared unit; actual unit is what gets written)

**Step 3a.4 — Record shape, then separately assess remediation.**

The shape itself is reported neutrally. Whether it becomes a finding — and at what severity — depends on remediation posture:

**For One-to-one:** No finding. Report the shape observation in Summary, move on.

**For One-to-many:** Assess two separate questions.

*Question A — Can the sub-units be independently queued / split?*
- Yes: the proper fix is dispatcher/performer — split the queue so each sub-unit is an atomic transaction. Use this when sub-units are independent (one invoice, one employee record, one order, one file).
- No: the domain forces a sequential session-bound submission (SAP new-plan enrollment, carrier portal group application, bank multi-step wire). Queue splitting is infeasible. The fix is not architectural — it is operational: verify atomicity, error handling, crash recovery, and progress tracking using the **10-point hardening checklist** in [rpa-common-issues.md](references/rpa/rpa-common-issues.md) → "When it cannot be split — hardening checklist." Each missing safeguard is a separate finding.

*Question B — What partial-failure recovery exists today?*

Look for any of these patterns (semantically, not by filename):

| Pattern | Detection |
|---|---|
| Read-check-before-write before each sub-unit write | Inspect activity sequence in the loop body |
| Conditional skip based on "already exists/processed" state | Inspect If/Switch branches wrapping writes |
| Orchestrator queue dedup via `UniqueReference` | Check `Add Queue Item` properties |
| SQL idempotent writes (`MERGE`, `ON CONFLICT`, `UPSERT`, `WHERE NOT EXISTS`) | Grep SQL statements |
| HTTP idempotency (`Idempotency-Key` header, ETag `If-Match` / `If-None-Match`) | Check HTTP Request headers |
| Status-column filters (`WHERE Status != 'Processed'`) | Grep queries |
| Pre-check workflow invocation (names often contain `check`/`verify`/`exists`/`processed`/`already`/`skip`/`idempoten` — one of many forms, not the only signal) | Inspect invoked workflow names and bodies |
| Per-sub-item progress written to queue `Output` / Data Service / external state | Inspect what's persisted during the loop |

**Severity and finding framing:**

| Scenario | Severity | Finding framing |
|---|---|---|
| One-to-many + sub-units splittable + no idempotency guards + `MaxRetryNumber` < 2 | **Critical** | "Transaction granularity: split into dispatcher/performer. Current architecture risks partial-state corruption on transient failure." |
| One-to-many + sub-units splittable + idempotency guards exist but progress/output fidelity weak | **Warning** | "Transaction granularity: consider dispatcher/performer split for better analytics and retry isolation." |
| One-to-many + sub-units NOT splittable (domain constraint) + missing safeguards | **Warning–Critical** | "Cannot be split — run the 10-point hardening checklist in [rpa-common-issues.md](references/rpa/rpa-common-issues.md) → 'When it cannot be split.' Report each missing safeguard as a separate finding." |
| One-to-many + splittable + guards + retry + per-sub-item output | Info (tech debt) | "Transaction granularity: working with compensation; consider dispatcher/performer if volume grows." |
| Unclear | Info | "Unit of work ambiguous — schema/code documentation gap." |

The shape observation belongs in the **Executive Summary** of the report as a one-liner (see Step 5). Any finding generated from the shape analysis becomes a normal numbered finding in the Critical/Warning/Info sections — not a separate "Unit of Work Analysis" block.

#### 3b. PDD Alignment Review (if PDD is available)

If a PDD was found or provided in Step 0, use it as the **primary benchmark** for the manual review. For each project, verify:

| PDD Section | What to Check | Severity if Mismatched |
|---|---|---|
| Business process description | Does the implementation match the described process flow? | Warning |
| Expected inputs/outputs | Do workflow arguments match PDD-defined inputs and outputs? | Warning |
| Exception handling requirements | Are Business Exceptions thrown for the cases the PDD defines? Are retries configured per PDD specs? | Warning |
| Application list | Are all applications from the PDD automated? Any missing? Any extras not in PDD? | Warning |
| Transaction definition | Does the transaction item structure match the PDD? | Warning |
| Queue specifications | Queue names, retry counts, SLAs match PDD? | Warning |
| Credential requirements | Are all credentials from PDD stored securely (assets/vault)? | Critical if hardcoded |
| SLAs and performance targets | Does the automation design support PDD-defined throughput/timing? | Info |
| Happy path + exception scenarios | Are all PDD-documented scenarios handled? | Warning |
| Out of scope items | Does the automation stay within PDD-defined scope? | Info |

**Report PDD mismatches** as a dedicated section in the review report. A technically sound automation that doesn't match its PDD is still a problem.

If no PDD is available, skip this sub-step and note in the report:
> **Note:** No PDD was available for this review. Business logic alignment could not be verified. This review covers technical quality and best practices only.

#### 3c. Technical Quality Review

For **each** project, load the type-specific checklist:

For **Solution / Multi-project scope**, also perform solution-level checks from [references/solution-review-guide.md](references/solution-review-guide.md):
- Solution structure validation (.uipx, config.json, orphan projects) — **skip `.uipx` checks if any detected executable is Windows-Legacy; recommend migration instead**
- Cross-project dependency checks
- Configuration consistency across projects
- Multi-project architecture pattern assessment

For deep-dive RPA reviews, also consult:
- RPA (advanced): [rpa-advanced-checklist.md](references/rpa/rpa-advanced-checklist.md) — project organization, selector robustness, variable hygiene, data patterns, error handling depth, testing maturity, idempotency
- RPA (long-running): [long-running-workflow-issues.md](references/rpa/long-running-workflow-issues.md) — load when project uses persistence activities (`Suspend`, `Wait and Resume`, `Create Form Task`, Orchestration Process type)
- RPA (Modern Studio): [modern-studio-issues.md](references/rpa/modern-studio-issues.md) — load for Studio 2024.10+ projects (Modern vs Classic mixing, coded/XAML interop, Object Repository, Data Manager, Healing Agent)
- Document Understanding: [du-review-checklist.md](references/document-understanding/du-review-checklist.md) — load when DU packages detected in `project.json` dependencies

For common antipatterns per project type, also consult:
- RPA: [rpa-common-issues.md](references/rpa/rpa-common-issues.md)
- Agents: [agent-common-issues.md](references/agents/agent-common-issues.md)
- Flows: [flow-common-issues.md](references/flows/flow-common-issues.md)

### Step 4 — Evaluate Optimization

Only after validation (Step 2) and manual review (Step 3) are complete, evaluate optimization.

**Solution / Multi-project scope** — evaluate cross-project concerns:
- **Architecture:** Is the multi-project design appropriate (dispatcher/performer, main + libraries, flow + resources)?
- **Cross-project dependencies:** Are library versions pinned? Any circular dependencies?
- **Queue usage:** Should this solution use queues for work distribution?
- **Bulk operations:** Are there loops that could use bulk APIs?
- **Transaction handling:** Is error recovery and retry properly implemented across projects?
- **Resource efficiency:** Are there redundant API calls, excessive logging, or unnecessarily large files?
- **Configuration consistency:** Do all projects use the same pattern for configuration (assets, config.json)?

**Single Project scope** — evaluate within-project optimization:
- **Queue usage:** If processing >50 independent items, should this use queues?
- **Bulk operations:** Are there loops with individual API calls that could be batched?
- **Transaction handling:** Is REFramework or equivalent retry logic needed?
- **Resource efficiency:** File sizes, logging volume, selector efficiency, data handling patterns

Read [references/review-workflow-guide.md](references/review-workflow-guide.md) for the full optimization evaluation criteria.

Read [references/architecture-assessment-guide.md](references/architecture-assessment-guide.md) for the architecture-level evaluation framework — process suitability, complexity classification, environment separation, and architecture principles scoring.

### Step 5 — Produce the Review Report

Output a structured report in chat (do NOT create a file):

**Report rules — do not violate:**

1. NEVER use internal workflow labels in the output. Forbidden terms: "Path A", "Path B", "Step 3a", "Step 0c", "Mismatch"/"Aligned" (use "one-to-one" / "one-to-many" / "unclear"), "disqualifying criteria", "verdict". The report is for the user, not a trace of the skill's internal workflow.
2. Do NOT create a separate "Unit of Work Analysis" section. The shape observation is a one-liner in the Summary. If the shape analysis produces a concern, it becomes a normal numbered finding.
3. Size metrics per file type use **activity / variable / node counts**, not "lines". Lines are meaningless for XAML and misleading for any file. See "Structural Metrics" table below.
4. Validation Status for Legacy projects says "Use `uipath-rpa` (Legacy mode) for Legacy-specific validation" — it does NOT say "Could not run" or "Failed". Legacy is supported indefinitely in Studio LTS; the `uip rpa` CLI targets Modern projects (Legacy mode uses the `uip rpa-legacy` CLI internally).

**Structural metrics to report (never "lines"):**

| File type | Metrics to use |
|---|---|
| `.xaml` | Activity count, max nesting depth, root-scope variable count, argument count, invoke-workflow count |
| `.cs` (coded workflow) | Method count, statement count (LOC excluding blank/comment), class count |
| `.flow` | Node count, gateway count, longest path depth, subflow count |
| `.py` (coded agent) | Function count, statement count, import count |
| Config (JSON/XLSX) | Entry count, nesting depth |

**Required report structure:**

```markdown
## Review Report: <Project or Solution Name>

### Summary
- **Overall Quality:** Good / Needs Improvement / Critical Issues
- **Business Value:** <1-2 sentence description of what this automation does>
- **Review Scope:** Single project / Solution (N projects) / Multi-project repo (N executables + M libraries)
- **Project Types Found:** <list with type and language, e.g., "RPA (XAML, VisualBasic)", "Agent (Coded, Python)">
- **Validation Status:** <per project: pass with counts, or "Validation via uipath-rpa (Legacy mode)" for Legacy>
- **PDD Available:** Yes (path) / No — business logic alignment not verified
- **Transaction Shape:** <one line per project, e.g., "Processes 1 invoice per invocation (one-to-one)." or "Processes 1 company per invocation; internally writes N employee enrollments (one-to-many) — see [W-002].">

### PDD Alignment (only if PDD was available)

| PDD Requirement | Implementation Status | Finding |
|---|---|---|
| ... | ... | ... |

> If no PDD: "No PDD was available for this review. Business logic alignment could not be verified."

### Automated Validation Results

| Project | File | Command | Errors | Warnings | Info |
|---|---|---|---|---|---|
| ... | ... | ... | ... | ... | ... |

**Validation Details:**
- [V-E-001] <project>/<file>: **<rule-id>** — <message>
- ...

> For Legacy projects, note: "Validation CLI (`uip rpa validate`, `uip rpa analyze`) targets Modern projects. Legacy validation runs through `uipath-rpa` Legacy mode (using the `uip rpa-legacy` CLI)."

### Rule Findings

| Project | Source | Errors | Warnings | Info | Skipped |
|---|---|---|---|---|---|
| ClassifierAgent | `uip agent review` + judgment catalog | 2 | 5 | 3 | 1 |
| TriageAgent | `uip codedagent review` + judgment catalog | 1 | 4 | 2 | 1 |

**From the review CLI (deterministic):**
- [C-D-001] `LOWCODE_MESSAGES_NO_USER` — `ClassifierAgent/agent.json` — messages[] has no role="user" entry. Fix: Add a `{"role": "user", "content": "..."}` message.
- [C-D-003] `FRAMEWORK_DEP_MISSING` — `TriageAgent/pyproject.toml` — langgraph.json present but uipath-langchain missing from [project] dependencies. Fix: Add `"uipath-langchain"` to [project] dependencies in pyproject.toml.

**From the judgment catalog (reasoning):**
- [W-D-002] `LC_PROMPT_ROLE_DEFINITION` — `ClassifierAgent/agent.json` — System prompt opens with task instructions before establishing the agent's role. Fix: Add an opening sentence: "You are an X that does Y."
- [W-D-004] `CODED_ERROR_HANDLING` — `TriageAgent/main.py` — `llm.ainvoke(...)` call has no try/except, fallback, or retry. Fix: Wrap the call in try/except with a fallback path or surface the error in the agent's output state.
- ...

**Rules Skipped (and why):**
- `uip codedagent review` — CLI not available in environment (deterministic checks not run)
- `LC_GUARDRAIL_EVALS_CONSISTENCY` — no eval set present to assess against

> The Rule Findings section is required for every agent project (low-code or coded). It is omitted for project types whose catalog has not yet been authored (RPA, flows, coded apps as of phase 1).

### Critical Findings (block deployment)
1. [C-001] <concise title> — `<project/file>` — <what to check + recommended fix>

### Warnings (should fix before production)
1. [W-001] <concise title> — `<project/file>` — <what to check + recommended fix>

### Improvement Opportunities
1. [I-001] <concise title> — `<project/file>` — <what to improve>

### Per-Project Summary
| Project | Type | Language | Size | Validation | Quality | Key Findings |
|---|---|---|---|---|---|---|
| ProjectA | RPA (Coded) | CSharp | 42 methods, 1,300 statements | 1 error, 2 warnings | Needs Work | V-E-001, W-001 |
| ProjectB | Flow | — | 18 nodes, 3 gateways, depth 5 | Pass | Good | I-001 |
| ProjectC | RPA (XAML) | VisualBasic | 84 activities, 50 vars, depth 12 | Via uipath-rpa (Legacy mode) | Needs Improvement | C-002, W-003 |

### Recommended Next Steps

Route each fix to the appropriate skill:

| Fix needed | Use skill |
|---|---|
| Fix RPA workflow / coded workflow / XAML / project.json | `uipath-rpa` |
| Fix RPA Windows-Legacy project | `uipath-rpa` (Legacy mode) |
| Fix agent (coded or low-code) | `uipath-agents` |
| Fix flow (.flow) | `uipath-maestro-flow` |
| Fix coded app | `uipath-coded-apps` |
| Fix Orchestrator resources (assets, queues, folders) | `uipath-platform` |
| Fix `.uipx` solution / pack / publish / deploy lifecycle | `uipath-solution` |

1. Fix [C-001] using `uipath-rpa` — change argument type to SecureString
2. ...

### Optimization Notes
- <queue usage, bulk operations, retry/idempotency observations — e.g., partial-failure handling for one-to-many shapes>
```

**Finding severity labels (never "Mismatch"/"Aligned"):**
- Overall Quality: `Good` / `Needs Improvement` / `Critical Issues`
- Transaction Shape: `one-to-one` / `one-to-many` / `unclear`
- Findings: `Critical` / `Warning` / `Info`

**Quality determination thresholds:**
- **Good** — 0 Critical, 0-3 Warnings
- **Needs Improvement** — 0 Critical, 4+ Warnings OR 1 Critical with clear fix
- **Critical Issues** — 2+ Critical OR 1 Critical with security/data-integrity implications

## Task Navigation

| I need to... | Read this |
|---|---|
| Understand the rule row schema | [rule-format.md](references/rule-format.md) |
| Run the review CLI + judgment catalog (Step 2.5) | [rule-catalog-workflow.md](references/rule-catalog-workflow.md) |
| Apply common rules for agents (both formats) | [agents-common-rules.md](references/agents/agents-common-rules.md) |
| Apply the low-code agent judgment catalog | [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
| Apply the coded agent judgment catalog | [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
| Understand the full review workflow in detail | [review-workflow-guide.md](references/review-workflow-guide.md) |
| Review a solution structure (.uipx) | [solution-review-guide.md](references/solution-review-guide.md) |
| Review an RPA project (coded or XAML) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
| Find common RPA issues | [rpa-common-issues.md](references/rpa/rpa-common-issues.md) |
| Review an agent project | [agent-review-checklist.md](references/agents/agent-review-checklist.md) |
| Find common agent issues | [agent-common-issues.md](references/agents/agent-common-issues.md) |
| Review a flow project | [flow-review-checklist.md](references/flows/flow-review-checklist.md) |
| Find common flow issues | [flow-common-issues.md](references/flows/flow-common-issues.md) |
| Review a coded app | [coded-app-review-checklist.md](references/coded-apps/coded-app-review-checklist.md) |
| Review Orchestrator resources | [platform-resources-checklist.md](references/platform/platform-resources-checklist.md) |
| Deep-dive an RPA project | [rpa-advanced-checklist.md](references/rpa/rpa-advanced-checklist.md) |
| Review a long-running / Orchestration Process (persistence, Wait/Resume, Suspend) | [long-running-workflow-issues.md](references/rpa/long-running-workflow-issues.md) |
| Review Modern Studio (2024.10+) specific concerns (Modern vs Classic, coded/XAML interop, Object Repo, Healing Agent) | [modern-studio-issues.md](references/rpa/modern-studio-issues.md) |
| Review a Document Understanding project | [du-review-checklist.md](references/document-understanding/du-review-checklist.md) |
| Assess architecture and process suitability | [architecture-assessment-guide.md](references/architecture-assessment-guide.md) |
| Review source control / CI-CD / DevOps readiness (any project type) | [devops-readiness-checklist.md](references/devops-readiness-checklist.md) |

## Anti-Patterns — What NOT to Do

1. **Do not modify files.** This is a review skill, not a builder. Identify issues, recommend fixes, and tell the user which skill to use.
2. **Do not review without running automated validation first.** Manual review alone misses structural issues that CLI tools catch instantly.
3. **Do not skip solution-level discovery.** Reviewing a single project without understanding the solution context leads to wrong optimization recommendations (e.g., suggesting queues when the solution already has a dispatcher/performer pattern).
4. **Do not report validation errors as manual findings.** Reference the validation output — do not re-describe what the CLI already reported.
5. **Do not provide a review without severity ratings.** Every finding must be Critical, Warning, or Info. An undifferentiated list of issues is not actionable.
6. **Do not recommend architecture changes without understanding business context.** Ask about volume, frequency, SLA, and error tolerance before suggesting queue-based processing, parallel execution, or other architectural patterns.
7. **Do not attempt to fix issues yourself.** Report the issue, suggest the fix, name the skill that can apply it. Stop there.
8. **Do not flag Windows-Legacy compatibility as Critical.** Legacy is supported **indefinitely** in Studio LTS — 2024.10, 2025.10, 2026.10, and all future LTS releases continue to support creating, opening, editing, running, and deploying Legacy projects. It is NOT a deployment blocker and NOT a mid-term support risk. Deprecation means "no new features added to Legacy," not "Legacy will be removed." Flag as **Warning** (if the project would benefit from capabilities Legacy lacks — see [rpa-review-checklist.md §10](references/rpa/rpa-review-checklist.md) for ranked feature list) or **Info** (if Studio LTS is the organizational standard or SOAP web services are required). When recommending migration, lead with the 2-3 features most relevant to the project's actual pain (typically **Healing Agent**, **Unified Target / Modern UIA**, **Object Repository**, **ScreenPlay**, **coded test cases**, **Autopilot**, **Agents/Maestro**). Route Legacy-specific deep validation to `uipath-rpa` (Legacy mode).
9. **Do not recommend removing a dependency without grepping for usages.** A package may be the sole supplier of an activity used elsewhere — recommend removal only after confirming no consumers exist.
10. **Do not flag `-preview` package versions.** Many UiPath packages currently ship preview-by-default during the public preview phase, and resolution defaults to bringing them in with explicit user confirmation. Surface stability concerns through activity-owner channels, not user-facing review reports.
11. **Do not run scripts or install Python packages from this skill.** Deterministic checks run in the `uip agent review` / `uip codedagent review` CLI (Step 2.5a), not via scripts. The skill itself ships no executable code.