uipath-review

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.
13. Grade every agent project by the rubric — derived, never asserted. For agent projects (phase 1), produce a letter grade (A/B/C/D/F, no +/-) per agent and overall, computed in Step 4.5 as min(G_det, G_jud). G_det is read from the review CLI's Data.Grade (Step 2.5a) — do not recompute it from finding counts. G_jud you compute from judgment (architecture scores + Step 2.5b + Step 3). CLI findings already shaped Data.Grade; only judgment findings feed G_jud, so each finding lands in exactly one sub-grade. Show the binding constraint for every grade; a grade with no shown derivation is invalid. A security or data-integrity judgment Critical forces F regardless of design quality (hard gate, not a blend). The skill grade is always ≤ Data.Grade (min only lowers) — report both, never overwrite the CLI grade. Do not grade non-agent projects (RPA, flows, coded apps) — that rubric is a future phase. See references/agents/agent-grading-rubric.md.

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):

# 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 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
project.json + .xaml workflow files	RPA (XAML)	rpa-review-checklist.md
project.json with expressionLanguage: "VisualBasic" and no/Legacy targetFramework	RPA (Windows-Legacy)	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
project.json + .xaml + DU packages in dependencies (UiPath.IntelligentOCR.Activities, UiPath.DocumentUnderstanding.ML.Activities)	RPA + Document Understanding	rpa-review-checklist.md + du-review-checklist.md
agent.json (no main.py)	Agent (Low-Code)	Checklist: agent-review-checklist.md. Rule catalog (Step 2.5): agents-common-rules.md + 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. Rule catalog (Step 2.5): agents-common-rules.md + agents-coded-rules.md
agent.json + main.py + pyproject.toml (agent-builder coded layout)	Agent (Low-Code + Coded)	Checklist: agent-review-checklist.md. Rule catalog (Step 2.5): all three — agents-common-rules.md + agents-lowcode-rules.md + agents-coded-rules.md
*.flow + project.uiproj with "ProjectType": "Flow"	Flow	flow-review-checklist.md
.uipath/ directory or app.config.json	Coded App	coded-app-review-checklist.md

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

| # | 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:

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):

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:

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:

### 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.

See 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:

# 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 → "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 → '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:

• 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 — project organization, selector robustness, variable hygiene, data patterns, error handling depth, testing maturity, idempotency
• RPA (long-running): 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 — 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 — load when DU packages detected in project.json dependencies

For common antipatterns per project type, also consult:

• RPA: rpa-common-issues.md
• Agents: agent-common-issues.md
• 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 for the full optimization evaluation criteria.

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

Step 4.5 — Compute the Agent Letter Grade (A–F)

Agent projects only (phase 1) — matching the Step 2.5 judgment catalog, which is agent-only today. Grade every agent project, and (for a multi-agent solution) the agent set overall, on an A–F scale. Non-agent projects are not graded yet (RPA, flows, coded apps are future phases) — report their findings without a grade. The grade is derived — never a fresh judgment. Take the worse of two sub-grades: G_det is read from the review CLI, G_jud you compute from judgment:

Final grade = min(G_det, G_jud)        where G_det = <review CLI>.Data.Grade

• G_det (deterministic) — read it from the review CLI; do not recompute. uip agent review / uip codedagent review (Step 2.5a) returns Data.Grade — that letter is G_det. (Data.Issues[] are still reported verbatim, but the grade comes from Data.Grade, not from tallying them.)
• G_jud (non-deterministic) — the only sub-grade you compute: the architecture-principle scores (1–5) in architecture-assessment-guide.md §4 + judgment-catalog (2.5b) + manual agent-checklist (Step 3) findings.

CLI findings already shaped Data.Grade (G_det); only judgment findings feed G_jud — so each finding lands in exactly one sub-grade.

G_jud band — average the applicable architecture-principle scores (Scalability is usually N/A for a single agent — exclude it and any other that does not apply, state which): 4.5–5.0→A, 3.5–4.49→B, 2.5–3.49→C, 1.5–2.49→D, 1.0–1.49→F. Then cap: any unmitigated judgment Critical → at most D; security/data-integrity judgment Critical → F.

Overall Agent Grade: single agent → its grade. Multiple agents → the worst per-agent grade. Never average grades.

Report the binding constraint in one line (e.g. "B — gated by G_det = CLI Data.Grade B; design strong (G_jud A)"). Since the skill grade is min(Data.Grade, G_jud), it is always ≤ Data.Grade — report both; never overwrite the CLI grade.

Full rubric, agent-principle scoring, edge cases (no-PDD / CLI-unavailable / no-eval-set), CLI-grade alignment, and worked examples: references/agents/agent-grading-rubric.md.

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:

## Review Report: <Project or Solution Name>

### Summary
- **Overall Quality:** Good / Needs Improvement / Critical Issues
- **Agent Grade:** <A–F> — <verdict label> (<binding constraint, e.g. "B — gated by G_det: 3 Warnings; design strong (G_jud A, arch avg 4.5)">) — *agent projects only; omit this line if the review has no agent projects*
- **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 | Grade | Key Findings |
|---|---|---|---|---|---|---|---|
| ClassifierAgent | Agent (Coded) | Python | 14 functions, 220 statements | Pass | Good | B | W-D-002 |
| ProjectA | RPA (Coded) | CSharp | 42 methods, 1,300 statements | 1 error, 2 warnings | Needs Improvement | — | 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 |

> The **Grade** column is the per-agent `min(G_det, G_jud)` from Step 4.5 — **agent projects only** (`—` for other types, phase 1). Append the review CLI's `Data.Grade` when it differs, e.g. `B (CLI: A)`. The **Quality** column (Good / Needs Improvement / Critical Issues) applies to every project type.

### 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 (all project types)
• Agent Grade: A / B / C / D / F (no +/-) — agent projects only; see Step 4.5 and agent-grading-rubric.md
• Transaction Shape: one-to-one / one-to-many / unclear
• Findings: Critical / Warning / Info

Overall Quality thresholds (all project types):

• 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

Agent Grade → verdict label (agent projects only; the line reads "B — Good"):

Grade	Verdict label
A / B	Good
C / D	Needs Improvement
F	Critical Issues

This maps the letter to the verdict word only. The agent grade is min(G_det, G_jud) from Step 4.5, where G_det is the review CLI's Data.Grade and the G_jud band lives in Step 4.5 — do not restate either here.

Task Navigation

I need to...	Read this
Compute the A–F letter grade for an agent (Step 4.5)	agent-grading-rubric.md
Understand the rule row schema	rule-format.md
Run the review CLI + judgment catalog (Step 2.5)	rule-catalog-workflow.md
Apply common rules for agents (both formats)	agents-common-rules.md
Apply the low-code agent judgment catalog	agents-lowcode-rules.md
Apply the coded agent judgment catalog	agents-coded-rules.md
Understand the full review workflow in detail	review-workflow-guide.md
Review a solution structure (.uipx)	solution-review-guide.md
Review an RPA project (coded or XAML)	rpa-review-checklist.md
Find common RPA issues	rpa-common-issues.md
Review an agent project	agent-review-checklist.md
Find common agent issues	agent-common-issues.md
Review a flow project	flow-review-checklist.md
Find common flow issues	flow-common-issues.md
Review a coded app	coded-app-review-checklist.md
Review Orchestrator resources	platform-resources-checklist.md
Deep-dive an RPA project	rpa-advanced-checklist.md
Review a long-running / Orchestration Process (persistence, Wait/Resume, Suspend)	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
Review a Document Understanding project	du-review-checklist.md
Assess architecture and process suitability	architecture-assessment-guide.md
Review source control / CI-CD / DevOps readiness (any project type)	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 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.