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 manually modify any files.** This skill is read-only. Exception: The command `uip agent refresh` is allowed and mandatory for low code agents, because it is not a manual modification, even when the command updates derived files -- do not restore or clean up those CLI-managed changes. 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-maestro-bpmn, uipath-api-workflow, 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). For low-code agents, run `uip agent refresh` and `uip agent validate`. Run `uip maestro flow validate` on flows, `uip maestro bpmn validate` on BPMN processes, `uip api-workflow validate` on API workflows. 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 format-specific judgment catalog (`agents-lowcode-rules.md` or `agents-coded-rules.md`). Future phases add catalogs for RPA, flows, coded apps. This holds even when the skill loads mid-task: if review work already started before this skill loaded (e.g., a generic code-review pass produced findings), Step 2.5a and the guardrail Step 0 catalog fetch are still mandatory — run them, then merge the earlier findings into this skill's report format. Prior review output is never a substitute for the review CLI or the live catalog. 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](references/agents/agent-grading-rubric.md). 14. **These paths are CLI-managed — `uip agent refresh` owns them:** `.agent-builder/`, `.local/build/`, and (low-code only) the root `entry-points.json`, regenerated from `agent.json`. Do not open their contents. Exclude them from classification, source-file selection, structural metrics, and manual checks. Raise a finding only when `refresh` fails to fix them — a pre-refresh mismatch is stale by construction, not a defect. Read low-code schemas from `agent.json` (`.inputSchema` / `.outputSchema`). ## 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 \( -type d \( -name ".agent-builder" -o -path "*/.local/build" \) \) -prune -o \( -name "*.uipx" -o -name "project.json" -o -name "project.uiproj" -o -name "agent.json" -o -name "*.flow" -o -name "*.bpmn" -o -name "app.config.json" -o -name ".uipath" -o -name "pyproject.toml" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) -print 2>/dev/null # Search for PDD or design documents find . -maxdepth 3 \( -type d \( -name ".agent-builder" -o -path "*/.local/build" \) \) -prune -o \( -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*" \) -print 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 a low-code `agent.json`, OR a coded-agent Python project (`pyproject.toml` + framework/`uipath.json` configuration), OR `.flow`, OR `project.uiproj` with `ProjectType` `Flow`/`ProcessOrchestration`/`Api` - 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, or one Python coded-agent project, 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 no `targetFramework` or `targetFramework: "Legacy"` (any expression language — Legacy C# exists) | 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` with `"type": "lowCode"` | Agent (Low-Code) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) | | Python coded-agent project, including `agent.json` with `"type": "coded"` when present | Agent (Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [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) | | `*.bpmn` + `project.uiproj` with `"ProjectType": "ProcessOrchestration"` | Maestro BPMN | [bpmn-review-checklist.md](references/bpmn/bpmn-review-checklist.md) | | `Workflow.json` (`document.dsl` + `do[]`) + `project.uiproj` with `"ProjectType": "Api"` | API Workflow | [api-workflow-review-checklist.md](references/api-workflows/api-workflow-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 |