fix(maestro-case): structured filter tree docs, reference-ID reuse warning

[song-zhao-25]

Summary

Two skill doc fixes ported from flow-tool IS changes (identified during flow-to-case connector sync analysis).

1. Structured filter tree (MST-8802 / Skills#304)

• connector-trigger-common.md §7: replace flat JMESPath filter table with structured filter tree shape, 13 operators + SDK enum reference, 3 examples (single, multi-AND, nested AND/OR)
• connector-trigger-common.md §essentialConfiguration: filter field is now <filter-tree-or-null>, not hardcoded null
• connector-trigger-common.md §Input body: note CLI auto-generates JMESPath from tree
• connector-trigger-common.md §What NOT to Do: replace "filter stays null" with "don't hand-write JMESPath" + "don't use filterExpression"
• connector-integration.md: add note that JSON write path uses structured trees
• Documents dynamic =vars.X limitation (SDK only supports literal values)

2. Reference-ID reuse warning (Skills#348)

• connector-trigger-common.md §What NOT to Do: add anti-reuse rule
• connector-activity/impl-json.md §What NOT to Do: add anti-reuse rule
• "Never reuse a reference ID from a prior case or session — always resolve fresh via uip is resources execute list"

Files changed (3)

• skills/uipath-maestro-case/references/connector-trigger-common.md
• skills/uipath-maestro-case/references/connector-integration.md
• skills/uipath-maestro-case/references/plugins/tasks/connector-activity/impl-json.md

Test plan

• Verify connector-trigger-common.md shows structured filter tree format with operators + examples
• Verify essentialConfiguration template uses <filter-tree-or-null> not null
• Verify ref-ID reuse warning present in both connector-trigger and connector-activity docs
• Verify connector-integration.md has structured tree note in Filter Syntax section

🤖 Generated with Claude Code

[github-actions]

Claude finished @song-zhao-25's task in 2m 27s —— View job

---

Summary

Documentation-only PR with three targeted fixes to the uipath-case-management skill: (1) replaces the flat JMESPath filter table with a structured filter tree format, operators, and examples in connector-trigger-common.md, (2) adds a reference-ID reuse warning to both connector-trigger and connector-activity docs, and (3) fixes a broken cross-skill slug link in case-commands.md.

Change-by-Change Review

1. references/connector-trigger-common.md — Structured filter tree + ref-ID warning

Severity: OK (with one Low note)

The core change: §7 now documents a structured filter tree shape with groupOperator, filters[], groups[], and a proper operator table (Equals, Contains, GreaterThan, etc.). This replaces the old flat JMESPath table. The examples (single filter, multi-filter AND, no-filter) are clear and copy-paste ready.

Supporting changes are consistent:

• essentialConfiguration template (line 230): null → <filter-tree-or-null> — correct placeholder
• Line 235: New note explains when filter tree goes in essentialConfiguration.filter vs staying null — properly reverses the old "always null" rule
• Lines 140–142: Dynamic variable limitation section documents the =vars.X workaround (fall back to direct JMESPath + null filter) — good edge case coverage
• Lines 266–269: "What NOT to Do" rules updated to match new filter tree approach
• Line 269: Ref-ID reuse warning added — clear and actionable

Low note: The Input body example at line 243 still shows a JMESPath expression in body.filters.expression. The preceding prose (line 239) clarifies this is auto-generated by the CLI from the filter tree, so it's showing the output not something the agent writes. This is technically correct but an agent could misread the example as a template to fill in. Consider adding a brief inline note like (auto-generated from filter tree) after the expression value.

2. references/connector-integration.md — Filter tree bridge note

Severity: OK

Two-line addition at line 117 — bridge content linking to connector-trigger-common.md §7 for the structured filter tree details. Follows reference pointer discipline: states the relevant fact for this file's context (JSON write path uses trees, CLI --filter flag is backward compat only) and links to the authority. No content duplication.

3. references/case-commands.md — Cross-skill link fix

Severity: OK

Line 47: See [uipath-platform](/uipath:uipath-platform) → See the \uipath-platform` skill. The /uipath:uipath-platform` slug is a plugin-internal link that doesn't resolve in markdown. Plain text reference is the correct fix per the self-contained skill rule.

4. references/plugins/tasks/connector-activity/impl-json.md — Ref-ID warning

Severity: OK

Single line added at line 270 in "What NOT to Do". Consistent with the equivalent warning in connector-trigger-common.md — slightly different examples (Jira project keys, Slack channel IDs vs mailbox folders, Slack channels, Jira projects) appropriate to each file's context.

What's Missing

• No e2e-tagged test task exists for uipath-case-management — both existing tests (init_validate.yaml, registry_discovery.yaml) are tagged smoke only. This is a pre-existing gap, not introduced by this PR. Medium (pre-existing).
• Nothing else identified. The changes are well-scoped documentation fixes that don't introduce new CLI workflows requiring new test coverage.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Not modified — no changes to SKILL.md
E2E Tests	Pre-existing gap	No e2e-tagged tasks; both existing are smoke. Not introduced by this PR
Skill Body	OK	Changes are in reference files only
References & Assets	OK	All relative links resolve; no orphaned files; no cross-skill refs
Repo Hygiene	OK	CODEOWNERS entry exists; no secrets/paths; changes scoped to one skill

Issues for Manual Review

• Filter tree schema accuracy: The structured filter tree format (groupOperator, filters[], groups[], operator names) should be verified against the actual SDK/CLI implementation. The reviewer cannot confirm whether these field names and operator strings match the runtime.
• Dynamic variable limitation workaround: Line 142 says to "write the body.filters.expression JMESPath string directly" when =vars.X is needed. Verify this fallback path still works with current CLI versions.

Conclusion

Clean documentation PR. All three fixes are well-scoped, internally consistent, and follow repo conventions. No critical or high issues. One Low observation about the body example potentially being misread. The pre-existing lack of e2e test coverage is worth tracking but not blocking for this PR. Approve.