[ENGCE-57552] skills(uipath-maestro-flow, uipath-platform): array filter + mandatory-filter contract

[baishalighosh]

Jira: ENGCE-57552 — [Skills][CLI] Add support for array filter in trigger
RCA: ENGCE-57498 — Gmail Email Received trigger returns 400 on Debug (Confluence)
Companion PR: skills #N — array filter smoke test (the matching trigger_with_array_filter.yaml eval ships separately so reviewers can land docs and tests independently).

Expected

No user configured filters
filterExpression: "(ParentFolders[?ID=='INBOX'])"

Actual agent generated

Both work as expected

[github-actions]

Claude finished @baishalighosh's task in 2m 26s —— View job

---

PR Review: [ENGCE-57552] array filter + mandatory-filter contract

• Read review criteria and project conventions
• Get full diff and PR comments
• Read full changed files for context
• Verify relative links resolve
• Check for cross-skill references, secrets, naming conventions
• Post review

---

Summary

Two doc updates aligned with the CLI fix in uipcli #1823: (1) impl.md in uipath-maestro-flow removes the stale "array filters not supported" anti-pattern row, replaces the inline 7-step filter-authoring procedure with a surface-specific Step 1 + link-out, and adds the mandatory-filter duplicate-clause warning; (2) triggers.md in uipath-platform gains a new canonical "Building Filter Trees from filterFields" section covering the authoring procedure, mandatory-filter pipeline contract, and array-projection emission.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/author/references/plugins/connector-trigger/impl.md

Severity: Medium

1a. Step 3 truncation (line 134) — intentional but loses agent guidance.
The old Step 3 included AskUserQuestion dropdown guidance and a link to SKILL.md. The new text just says "ask the user — list the missing fields with their displayName". The dropdown-vs-freeform guidance was valuable for agent behavior — it told the agent how to ask (dropdown when finite options exist). This removal is unrelated to the filter-tree changes and silently drops a behavioral instruction.

1b. Filter-tree authoring extraction (lines 300-302) — good reference pointer discipline.
Replacing the 7-step inline procedure with Step 1 (surface-specific flow registry get) + a link to the canonical procedure in uipath-platform is the right pattern. The bridge content is minimal and appropriate. The added field description hints (name, type, description) in the retained Step 1 are a useful improvement.

1c. Mandatory-filter anti-pattern row (line 314) — correct and well-written.
Replaces the stale "array filters not supported" row with the mandatory-filter duplicate-clause warning. The explanation is clear: set via eventParameters, not filter.

2. skills/uipath-platform/references/integration-service/triggers.md

Severity: High (cross-skill reference)

2a. New "Building Filter Trees from filterFields" section (lines 125-149) — well-structured.
The 6-step procedure, mandatory-filter subsection, and array-shaped fields subsection are clear and prescriptive. Content follows token-optimization rules (fragments OK, no filler). The mandatory-filter contract explanation (buildMandatoryFilterExpression → mandatoryFilterExpression → combinedFilterExpression) gives the agent the architectural context to understand why duplicating is wrong.

2b. Cross-skill reference introduced (line 134) — violates self-containment rule.
The new Step 2 links back to uipath-maestro-flow:

(see the operator table in the consuming skill — e.g. [uipath-maestro-flow > connector-trigger](...impl.md#supported-operators))

uipath-platform had zero references to uipath-maestro-flow on origin/main. This PR introduces the first one. Per CLAUDE.md: "Skills MUST be self-contained — no references to other skills." The uipath-platform skill is a shared foundation — it should not point to a consuming skill.

Fix: Remove the example link. The parenthetical can stay generic:

2. Choose an operator based on the user's intent and the field type (see the operator table in the consuming skill's trigger reference).

This keeps the instruction useful without creating a cross-skill dependency from the shared platform skill to a specific consumer. Fix this →

2c. TOC updated correctly (line 16).
New entry placed between "Response Fields" and "Webhook URL Retrieval" — correct position.

What's Missing

• AskUserQuestion / dropdown guidance removed from Step 3 (impl.md:134): The old text linked to SKILL.md's dropdown rule for finite-value fields. If this removal is intentional (e.g., the guidance moved elsewhere), the PR description should note it. If unintentional, restore it. The removal is unrelated to the filter-tree / mandatory-filter changes.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes in this PR
E2E Tests	OK	Doc-only change; PR description notes the smoke test ships separately
Skill Body	OK	SKILL.md not modified
References & Assets	Issue	Cross-skill link from uipath-platform → uipath-maestro-flow (line 134 of triggers.md)
Repo Hygiene	OK	No secrets, no personal paths, CODEOWNERS already covers both paths, changes scoped to the two relevant files

Issues for Manual Review

• CLI accuracy: The mandatory-filter pipeline description (buildMandatoryFilterExpression → essentialConfiguration.mandatoryFilterExpression → combinedFilterExpression) matches the PR description's architecture context, but I cannot verify it matches the actual CLI implementation in uipcli #1823.
• Array projection syntax: The JMESPath examples ((tags[?@=='urgent']), (ParentFolders[?ID=='INBOX'])) should be verified against the JmesHelper output in the CLI to ensure exact syntax parity.
• Merge ordering: PR description says to merge only after uipcli #1823 lands — reviewer should verify that dependency before approving.

Conclusion

Good documentation refactor that correctly extracts the filter-authoring procedure to the shared platform skill and adds valuable mandatory-filter / array-projection guidance. Two items to address before merge:

1. High: Remove the cross-skill back-link from uipath-platform/triggers.md line 134 to uipath-maestro-flow — replace with a generic reference to "the consuming skill's trigger reference."
2. Medium: Confirm the Step 3 AskUserQuestion dropdown guidance removal (impl.md line 134) is intentional — if not, restore it.

---