@uipath/skills 1.195.0

package/skills/uipath-review/references/flows/flow-common-issues.md

@@ -0,0 +1,280 @@
+# Flow Common Issues
+
+Catalog of frequently found issues in UiPath Flow projects, with detection methods and recommended fixes.
+
+## Structural Issues
+
+### Missing targetPort on Edges
+
+**Symptom:** Edge definitions lack the `targetPort` field.
+
+**Impact:** Flow validation fails. The flow cannot be executed.
+
+**Detection:** `uip maestro flow validate` will catch this. Also check manually:
+```bash
+# In the .flow file, look for edges without targetPort
+grep -c '"targetPort"' *.flow
+# Compare to total edge count
+```
+
+**Fix:** Add `"targetPort": "input"` to every edge that's missing it. Most nodes use `"input"` as the standard target port.
+
+### Hand-Written Definitions
+
+**Symptom:** Node definitions in the `.flow` file were manually written instead of copied from the flow registry.
+
+**Impact:** Incorrect schemas cause validation errors, runtime failures, or silent data loss. Hand-written definitions often miss required fields, have wrong types, or use outdated schemas.
+
+**Detection:** Compare definitions entries against registry output:
+```bash
+uip maestro flow registry get <node-type> --output json
+```
+If the definition in the .flow file doesn't match the registry output, it was likely hand-written.
+
+**Fix:** Replace hand-written definitions with the exact output from `uip maestro flow registry get`. Never modify registry definitions manually.
+
+### Orphan Nodes
+
+**Symptom:** Nodes exist in the `nodes` array but have no incoming edges (except the Start node) — they're unreachable.
+
+**Impact:** Orphan nodes suggest incomplete implementation or leftover design artifacts. They won't execute but add confusion.
+
+**Detection:** For each node (except Start), verify at least one edge targets it:
+1. Collect all `targetNodeId` values from edges
+2. Check each non-trigger node's ID appears in that list
+
+**Fix:** Either connect the orphan node to the flow or remove it. If it's a placeholder for future work, replace with a comment or remove and note in documentation.
+
+### Duplicate Node or Edge IDs
+
+**Symptom:** Two or more nodes or edges share the same ID.
+
+**Impact:** Validation fails. Runtime behavior is undefined — the engine may route to the wrong node.
+
+**Detection:** `uip maestro flow validate` catches this. Also check with:
+```bash
+# Extract all node IDs and check for duplicates
+python3 -c "import json; f=json.load(open('*.flow')); ids=[n['id'] for n in f['nodes']]; print([x for x in ids if ids.count(x)>1])"
+```
+
+**Fix:** Assign unique UUIDs to duplicate nodes/edges.
+
+## Design Issues
+
+### Stale Mock Placeholder Nodes
+
+**Symptom:** `core.logic.mock` nodes remain in the flow, used as stand-ins during development for resources that should now be published.
+
+**Impact:** Mock nodes don't execute real logic. The flow appears to work but produces no real results.
+
+**Detection:**
+```bash
+grep "core.logic.mock" *.flow
+```
+
+**Fix:** Replace each mock with the real resource node. Use `uip maestro flow registry get <resource-type>` to get the correct definition, then update the node type, inputs, and definitions.
+
+### Missing Output Mapping on End Nodes
+
+**Symptom:** End nodes (`core.control.end`) don't map `out` variables from the flow's variable declarations.
+
+**Impact:** Flow completes but output variables are empty/null. Callers of this flow receive no results.
+
+**Detection:** Read the `.flow` file:
+1. Identify all variables with `"direction": "out"` or `"direction": "inout"` in the `variables.globals` array
+2. For each reachable End node, verify these variables are mapped in the End node's inputs
+
+**Fix:** Add output variable mappings to every reachable End node. Each `out` variable must be explicitly set.
+
+### In Variable Mutation
+
+**Symptom:** Flow modifies a variable declared with `"direction": "in"`.
+
+**Impact:** Runtime error or silent failure. Input variables are read-only by design.
+
+**Detection:** Check variable directions in the `.flow` variables section. Then trace which nodes assign values to those variables. Any assignment to an `in` variable is a bug.
+
+**Fix:** Change the variable direction to `inout` if it genuinely needs to be modified. Or create a separate working variable and copy the input value.
+
+### console.log in Script Nodes
+
+**Symptom:** Script nodes contain `console.log()` statements.
+
+**Impact:** `console.log` output goes nowhere in the flow runtime. It's a debugging artifact that serves no purpose in production.
+
+**Detection:**
+```bash
+grep "console.log" *.flow
+```
+
+**Fix:** Remove `console.log` statements. If logging is needed, use flow-level logging or output the value to a variable for inspection.
+
+### Script Nodes Returning Bare Scalars
+
+**Symptom:** Script node returns a plain string, number, or boolean instead of an object.
+
+**Impact:** Downstream nodes may have difficulty accessing the value. Object returns are more extensible and consistent.
+
+**Detection:** Check script node output configurations. Look for `return "string"` or `return 42` patterns instead of `return { result: "string" }`.
+
+**Fix:** Wrap scalar returns in an object: `return { value: result }`.
+
+## Orchestration Issues
+
+### No Error Handling on Resource Nodes
+
+**Symptom:** Resource nodes (RPA, agent, human task) have only success edges — no error/failure paths.
+
+**Impact:** If the resource fails, the flow has no recovery path. It will fault entirely instead of handling the error gracefully.
+
+**Detection:** For each resource node, check if there are edges on error/failure ports (not just success/output).
+
+**Fix:** Add error edges from resource nodes to appropriate handling logic (retry, skip, escalate, terminate).
+
+### Wrong Resource Type
+
+**Symptom:** Agent node used for deterministic rule-based logic, or Script node used for tasks requiring AI reasoning.
+
+**Example issues:**
+- `uipath.agent.autonomous` node used to apply a fixed discount table (should be Script)
+- `core.action.script` used to classify free-text customer complaints (should be Agent)
+
+**Detection:** Review each node's purpose against its type. Agent nodes should handle ambiguity; Script nodes should handle deterministic logic.
+
+**Fix:** Replace with the appropriate node type. This may require publishing a new resource if switching from script to agent.
+
+### Stale Resource References
+
+**Symptom:** Resource nodes reference processes, agents, or APIs that have been unpublished, renamed, or moved to a different folder.
+
+**Impact:** Flow validation may pass (validates structure, not resource availability), but runtime execution fails when the resource is called.
+
+**Detection:** Extract resource keys from node types (e.g., `uipath.core.rpa-workflow.invoice-processor`). Verify each resource is published and accessible.
+
+**Fix:** Update resource references to point to current published resources. Re-run `uip maestro flow registry list` to find available resources.
+
+### Hardcoded Queue Names
+
+**Symptom:** Queue node inputs contain literal queue names instead of variable references.
+
+**Impact:** Cannot use different queues across environments. Requires flow modification for each deployment.
+
+**Detection:** Check queue node inputs for literal string values.
+
+**Fix:** Store queue name in a flow variable (preferably `in` direction) and reference it in the queue node.
+
+## Subflow Issues
+
+### Parent Variable Reference from Subflow
+
+**Symptom:** Subflow nodes reference `$vars.parentNodeId.output` — accessing the parent flow's variable scope.
+
+**Impact:** Subflows have their own variable scope by design. Parent `$vars` references are invalid and will fail.
+
+**Detection:** Check subflow node expressions for `$vars` references that point to nodes outside the subflow.
+
+**Fix:** Pass needed data as subflow input variables. Map parent data to subflow `in` globals.
+
+### Missing Subflow Start/End Nodes
+
+**Symptom:** Subflow body lacks a `core.trigger.manual` start or `core.control.end` end node.
+
+**Impact:** Subflow cannot execute. Validation fails.
+
+**Detection:** Check each subflow's nodes array for trigger and end types.
+
+**Fix:** Add Start and End nodes to the subflow.
+
+### Excessive Nesting
+
+**Symptom:** Subflows nested more than 3 levels deep.
+
+**Impact:** Difficult to understand, debug, and maintain. Variable mapping becomes complex and error-prone.
+
+**Detection:** Count nesting levels by traversing subflow containment.
+
+**Fix:** Flatten the hierarchy. Extract deeply nested logic into separate published flows that can be invoked as resource nodes.
+
+## Performance Issues
+
+### Sequential Processing of Independent Items
+
+**Symptom:** Items that could be processed in parallel are processed sequentially in a loop.
+
+**Impact:** Execution time scales linearly with item count. A 100-item batch takes 100x longer than it needs to.
+
+**Detection:** Check loop nodes for `sequential` mode when the items have no ordering dependency.
+
+**Fix:** Switch to parallel multi-instance mode. Note: parallel execution runs in batches of 50.
+
+### Large Payloads Through Unnecessary Nodes
+
+**Symptom:** Variables containing large data (full document content, large arrays) are carried through every node even when only a subset of nodes use them.
+
+**Impact:** Increases memory usage and serialization overhead at every node transition.
+
+**Detection:** Trace variable usage through the flow. Identify variables that are set early but only used much later.
+
+**Fix:** Use transform nodes to extract only needed fields early. Pass minimal data between nodes. Fetch full data only where needed.
+
+### Overly Complex Single Flows
+
+**Symptom:** A single .flow file with 30+ nodes handling multiple distinct concerns.
+
+**Impact:** Difficult to test, debug, and modify. Changes risk breaking unrelated logic.
+
+**Detection:** Count nodes in the flow. Identify distinct functional areas.
+
+**Fix:** Break into subflows by functional area. Or break into separate flows that call each other as resource nodes.
+
+## Maestro / BPMN Deadlock Patterns
+
+### Mixed Gateway Types on Merge (Deadlock)
+
+**Symptom:** Flow splits with a Parallel Gateway but merges with an Exclusive Gateway (or vice versa, or Inclusive split with Exclusive merge).
+
+**Impact:** Deadlock. Parallel split creates N tokens. Exclusive merge completes after the first token arrives and discards the rest — or hangs waiting for a condition that never satisfies. Orphaned tokens, flows hung forever.
+
+**Detection:** In `.flow` files, find every gateway split (diverging) and trace forward to its corresponding merge. Gateway types MUST match: Parallel → Parallel, Inclusive → Inclusive, Exclusive → Exclusive.
+
+**Fix:** Always use matching gateway types for split and merge. For "wait for all parallel branches", use a Parallel merge, not Exclusive.
+
+**Severity:** Critical
+
+### Variable Rename Without Fix-Variables Dialog
+
+**Symptom:** Flow variable renamed directly in the variables list (not via Fix Variables dialog). Expressions referencing the old variable ID silently break.
+
+**Impact:** Flow may save and validate but fails at runtime with "undefined variable" errors. Hard to diagnose because the variable appears to exist with the new name.
+
+**Detection:** After a rename, grep expression fields in the `.flow` file for references to the old variable UUID (not the display name).
+
+**Fix:** Use the Fix Variables dialog when renaming. If done manually, update every expression reference manually.
+
+**Severity:** Warning
+
+## API Workflow Antipatterns (Studio Web)
+
+### No Input Schema Enforcement
+
+**Symptom:** API workflow has input schema defined, but the first steps do not validate required inputs. Callers can send malformed payloads and the workflow tries to process them.
+
+**Impact:** NullReferenceException deep in the logic instead of a clear 400 Bad Request. Consumers get unhelpful errors.
+
+**Detection:** Inspect API workflow's initial activities. Check for explicit validation (required-field checks, type validation) before business logic begins.
+
+**Fix:** Add input validation as the first step. Return structured 400 responses with field-specific error messages.
+
+**Severity:** Warning
+
+### Synchronous Long-Running API Workflow
+
+**Symptom:** API workflow performing long-running logic (DB migrations, bulk processing, chained API calls) synchronously. Hard timeout: 10 minutes (5 min CPU for serverless).
+
+**Impact:** Request times out with no result, no recovery path. Caller sees timeout error. Work may be partially complete with no rollback.
+
+**Detection:** API workflow test execution exceeds 5 minutes.
+
+**Fix:** Convert to async pattern — accept request, return job ID, process in background (via queue), let caller poll. Or use `Wait for Event and Resume` for suspend/resume.
+
+**Severity:** Warning

package/skills/uipath-review/references/flows/flow-review-checklist.md

@@ -0,0 +1,316 @@
+# Flow Review Checklist
+
+Comprehensive quality checklist for UiPath Flow projects (`.flow` files) — orchestration of RPA processes, agents, apps, and human tasks.
+
+> **Unit of Work:** Before running the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For flows, the declared unit is in the `.flow` file under `variables.globals` with `direction: "in"` or `"inout"`. The actual unit is what the flow body produces — count downstream resource-node invocations and side effects per flow execution. If one flow invocation fans out to N downstream calls over a sub-collection of the input, that is a Granularity Mismatch (see [rpa-common-issues.md](../rpa/rpa-common-issues.md)).
+
+## 1. Structural Validation
+
+### File Presence
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| `.flow` file exists and is valid JSON | Critical | `cat *.flow \| python -m json.tool` |
+| `project.uiproj` exists with `"ProjectType": "Flow"` | Critical | Read project.uiproj |
+| `bindings_v2.json` exists (if external resources used) | Warning | `ls bindings_v2.json` |
+| `entry-points.json` present | Warning | `ls entry-points.json` |
+| `operate.json` present | Info | `ls operate.json` |
+
+### JSON Schema Compliance
+
+Run the CLI validator first:
+
+```bash
+uip maestro flow validate <ProjectName>.flow --output json
+```
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Flow validates without errors | Critical | `uip maestro flow validate` returns 0 errors |
+| All node IDs are unique | Critical | Check for duplicate IDs in nodes array |
+| All edge IDs are unique | Critical | Check for duplicate IDs in edges array |
+| Every edge has `targetPort` field | Critical | Check all edges for targetPort |
+| Every node type has a matching `definitions` entry | Critical | Compare node types to definitions array |
+| All nodeIds referenced in edges exist in nodes array | Critical | Cross-reference edge source/target with node IDs |
+
+### Node Integrity
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Start node exists (`core.trigger.manual` or `core.trigger.scheduled`) | Critical | Check nodes for trigger type |
+| At least one End node exists (`core.control.end`) | Critical | Check nodes for end type |
+| No orphan nodes (every node reachable from Start) | Warning | Trace edges from start to verify reachability |
+| Every `out` variable mapped on every reachable End node | Critical | Check End node output mappings |
+| No `core.logic.mock` placeholder nodes in production flows | Critical | Grep for `core.logic.mock` in nodes |
+
+## 2. Design Quality
+
+### Script Nodes
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Script nodes return objects (not bare scalars) | Warning | Check script node output types |
+| No `console.log` in script nodes | Warning | Grep for `console.log` in script content |
+| Expressions use `=js:` prefix correctly | Warning | Check expression syntax |
+| ES2020 subset used (no modern JS features beyond ES2020) | Warning | Check for unsupported syntax |
+| Script logic is testable and not overly complex | Info | Review script content |
+
+### Variable Management
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Variables have correct direction (`in`, `out`, `inout`) | Warning | Read `.flow` variables section |
+| `in` variables are NOT mutated (only `inout` can be modified) | Critical | Check for variable mutations |
+| Subflows don't reference parent `$vars` (own scope only) | Critical | Check subflow variable references |
+| Variable names are descriptive and consistent | Info | Review variable names |
+| No unnecessary variables (unused declarations) | Info | Cross-reference variable usage |
+
+### Edge and Port Configuration
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Every edge has both `sourcePort` and `targetPort` | Critical | Check edge definitions |
+| Decision node edges use correct port names (`true`/`false`) | Critical | Check decision node edges |
+| Switch node edges use correct case port names | Warning | Check switch node edges |
+| No duplicate edges between the same node pair on the same ports | Warning | Check for duplicate edges |
+
+## 3. Node-Specific Quality
+
+### Decision Nodes (`core.logic.decision`)
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Both `true` and `false` branches defined | Warning | Check outgoing edges |
+| Default branch defined (to avoid runtime faults) | Warning | Check for default path |
+| Condition expression is valid and testable | Warning | Read condition |
+| Fail-fast patterns used (check errors before processing) | Info | Review decision placement |
+
+### Loop Nodes (`core.logic.loop`)
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Loop has a clear exit condition | Critical | Check loop configuration |
+| Loop variable correctly references the collection | Warning | Check loop input |
+| Actions inside loop don't modify the collection being iterated | Warning | Check for collection mutation |
+| Parallel multi-instance batch size appropriate | Info | Check batch configuration |
+
+### Merge Nodes (`core.logic.merge`)
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Merge node present where parallel branches reconverge | Warning | Check parallel branch endings |
+| Merge type matches the gateway type (inclusive merge for inclusive gateway) | Warning | Compare gateway and merge types |
+
+### Subflow Nodes
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Subflow has its own Start and End nodes | Critical | Check subflow structure |
+| Nesting depth <=3 levels | Warning | Count nesting levels |
+| Input variables map to subflow `in` direction globals | Warning | Check variable mapping |
+| Output variables map to subflow `out` direction globals | Warning | Check output mapping |
+| Subflow used for repeated logic (not one-off sequences) | Info | Evaluate reuse potential |
+
+## 4. Resource Node Quality
+
+### Published Resources
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| All resource nodes reference published resources (not stale/missing) | Critical | Verify referenced resources exist |
+| Resource input schemas match flow variable types | Warning | Compare schemas |
+| Resource output mapped to flow variables correctly | Warning | Check output mappings |
+| Error handling configured on resource nodes | Warning | Check for error edges |
+
+### Resource Type Appropriateness
+
+| Resource Type | Correct Usage | Flag If |
+|---|---|---|
+| `uipath.core.rpa-workflow.*` | Invoking published RPA processes | Used for agent-type tasks |
+| `uipath.core.agent.*` | Invoking published AI agents | Used for deterministic rule-based tasks |
+| `uipath.core.human-task.*` | Requiring human input/approval | Used for automated decisions |
+| `uipath.agent.autonomous` | Classification, triage, reasoning | Used for simple data transformation |
+| `core.action.script` | Deterministic data transformation | Used for LLM reasoning tasks |
+
+### Agent Node vs Script Node Decision
+
+| Use Script When | Use Agent When |
+|---|---|
+| Logic is deterministic and rule-based | Input is ambiguous, requires reasoning |
+| Rules are known and enumerable | Natural language generation needed |
+| Data transformation, filtering, mapping | Classification, triage, or summarization |
+| Calculations, lookups, formatting | Understanding unstructured content |
+
+**Flag:** Agent nodes used for deterministic tasks as **Info** (unnecessary cost). Script nodes used for tasks requiring reasoning as **Warning** (insufficient capability).
+
+## 5. Orchestration Patterns
+
+### Dispatcher-Performer (Queue-Based)
+
+If the flow uses queues for work distribution:
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Queue create node properly configured | Warning | Check queue node inputs |
+| Wait-for-completion used when results needed | Warning | Check if `create-and-wait` vs `create` |
+| Queue name externalized (not hardcoded) | Warning | Check for literal strings |
+| Error handling for queue failures | Warning | Check error edges |
+
+### Sequential Pipeline
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Steps in correct order (no forward dependencies on undefined data) | Critical | Trace data flow |
+| Each step's output feeds correctly into next step's input | Warning | Check variable references |
+| Error at any step handled gracefully | Warning | Check error paths |
+
+### Fan-Out / Fan-In
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Loop properly splits work | Warning | Check loop node |
+| Results properly aggregated after loop | Warning | Check post-loop data handling |
+| Parallel batch size appropriate for workload | Info | Check batch configuration |
+
+## 6. Error Handling
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Resource nodes have error paths (not just success) | Warning | Check for error edges from resource nodes |
+| Terminate node used for unrecoverable errors | Info | Check for `core.logic.terminate` nodes |
+| Error information propagated to End node output | Warning | Check error variable mapping |
+| Timeout handling for long-running resource calls | Info | Check for timeout configuration |
+| Retry logic for transient failures | Info | Check retry configuration |
+
+## 7. Definitions Quality
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Definitions copied from registry (not hand-written) | Critical | Definitions should match registry format exactly |
+| Every node type has exactly one definitions entry | Critical | Cross-reference nodes and definitions |
+| No orphan definitions (types not used by any node) | Info | Cross-reference definitions and nodes |
+| Definition versions match node `typeVersion` | Warning | Compare versions |
+
+## 8. BPMN / Maestro Compliance (If Using Maestro)
+
+For flows that target UiPath Maestro execution:
+
+### BPMN Element Support (Execution-Ready)
+
+| Element Category | Supported for Execution | Modeling Only |
+|---|---|---|
+| **Start Events** | None, Message, Timer | Error, Signal, Conditional, Compensation, Escalation |
+| **Intermediate Catch** | Message, Timer | Signal, Conditional, Link |
+| **Boundary (Interrupting)** | Message, Timer, Error | Signal, Conditional, Escalation, Compensation |
+| **Boundary (Non-Interrupting)** | Message, Timer | Signal, Conditional, Escalation |
+| **End Events** | None, Message, Error, Terminate | Signal, Escalation, Compensation |
+| **Tasks** | User, Service, Send, Receive, Business Rule, Script, Manual | — |
+| **Gateways** | Exclusive, Parallel, Inclusive, Event-Based | Complex |
+| **Markers** | Multi-instance (parallel/sequential) | Loop, Compensation |
+| **Subprocesses** | Sub-process, Call Activity, Event Sub-process | Transaction |
+
+### Structural Checks
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| All BPMN elements used are execution-ready (not modeling-only) | Critical | Compare against support table above |
+| One clear start event and explicit end events | Critical | Check node structure |
+| Parallel gateways have matching parallel join gateways | Critical | Verify parallel synchronization |
+| Inclusive gateways have matching inclusive merge | Critical | Verify inclusive synchronization |
+| Default path defined on exclusive gateways (prevents runtime faults) | Warning | Check gateway configuration |
+| Task sizes are uniform in diagrams | Info | Visual review |
+| Flow direction is left-to-right or top-to-bottom | Info | Check node positions |
+| Separate process flow from business rules (use DMN Business Rule Tasks) | Info | Check for complex conditionals |
+
+### Timer Configuration
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Timer events use valid ISO 8601 durations (e.g., `PT1H`, `P1D`, `R/PT5M`) | Critical | Check timer values |
+| Timer boundary events configured for long-running tasks (SLA enforcement) | Info | Check boundary events |
+| Non-interrupting timers used when parallel execution is needed | Info | Check timer interrupt mode |
+| Cycle timers use correct repeat format (`R/P[duration]`) | Warning | Check cycle syntax |
+
+### Multi-Instance Configuration
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Parallel multi-instance batch size appropriate (runs in batches of 50) | Info | Check batch config |
+| Sequential multi-instance used when item ordering matters | Warning | Verify ordering requirement |
+| Multi-instance loops configured to **continue on individual item failure** (one item's error does not halt the entire batch) | Warning | Check multi-instance configuration for continueOnException/continue-on-failure flag. Batches of 50 where item #15 fails should still process items 16..50 |
+| Entry-points UUIDs are unique (no duplicates across entries in `entry-points.json`) | Critical | Parse `entry-points.json`, check for duplicate `uniqueId` values. Duplicates block publishing |
+| Nested loops use subprocess pattern (outer sequential, inner parallel) | Info | Check nesting pattern |
+
+### Error Handling in BPMN
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Error boundary events attached to tasks with failure risk | Warning | Check boundary events |
+| Error end events used for unrecoverable failures | Info | Check error paths |
+| Event subprocesses configured for centralized error handling | Info | Check event subprocesses |
+| Error mappings configured at element level (first match wins) | Warning | Check error mapping order |
+
+### Maestro vs Flow Decision
+
+If the project uses the simple Flow format (not full Maestro BPMN):
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Flow complexity appropriate (simple flows don't need Maestro) | Info | Assess process complexity |
+| Long-running processes use Maestro (not simple flows) | Warning | Check process duration |
+| Human-in-the-loop steps use Maestro User Tasks | Warning | Check for HITL requirements |
+| Process mining integration needed → use Maestro (auto-creates Process Optimization apps) | Info | Check monitoring needs |
+
+## 9. Performance and Optimization
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Decision nodes placed early (fail-fast patterns) | Info | Review decision placement |
+| Large payloads not carried through unnecessary nodes | Info | Check variable lifecycle |
+| Subflows used for repeated logic (DRY principle) | Info | Identify duplicated patterns |
+| Parallel execution used where items are independent | Info | Check for sequential processing of independent items |
+| Script nodes don't perform work that should be in RPA/agent resources | Warning | Review script complexity |
+
+## 10. Deployment Readiness
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Flow validates without errors | Critical | `uip maestro flow validate` |
+| All resource bindings resolved | Critical | Check bindings_v2.json |
+| No mock placeholder nodes remain | Critical | Grep for `core.logic.mock` |
+| Entry points correctly defined | Warning | Check entry-points.json |
+| Environment-specific values externalized | Warning | Check for hardcoded URLs/paths |
+| Debug flow succeeds end-to-end | Warning | `uip maestro flow debug <project-dir>` |
+
+## 11. Action Center / Human-in-the-Loop
+
+For flows that create human tasks via Action Center:
+
+### Task Design
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Actions have clear descriptions telling the user what to do and why | Warning | Review form task content |
+| Data is pre-filled — ask only for the decision the automation cannot make | Warning | Check form pre-population |
+| Deadlines configured on all human tasks (actions must not sit indefinitely) | Warning | Check deadline/SLA configuration |
+| Escalation rules defined (auto-escalate to manager if unresponded) | Warning | Check escalation configuration |
+| Assignment rules route actions to appropriate users/roles | Warning | Check task assignment logic |
+
+### Long-Running Workflow Patterns
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| `Suspend` activity used to release robot while waiting (not `Delay` or loop-wait) | Critical | Grep for Wait/Delay patterns — should use Suspend |
+| Timeout handling defined for unresponded actions | Warning | Check what happens if no one completes the task |
+| Process state serializable (all variables must survive suspend/resume) | Critical | Check for non-serializable variable types |
+| Robot is NOT held during human wait (process properly suspends) | Critical | Verify long-running workflow template is used |
+
+### Maestro Orchestration Patterns
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Each task assigned to correct executor type (robot, agent, or human) | Warning | Review task executor assignments |
+| Case management configured for individual case tracking | Info | Check case/instance management setup |
+| Process Apps configured for user-initiated process starts | Info | Check if Process Apps are set up for business user access |
+| End-to-end cycle time monitored (identify bottlenecks across actors) | Info | Check monitoring dashboards |
+| Agent tasks have guardrails and fallback to human escalation | Warning | Review agent task configuration |