fix(uipath-maestro-flow): document node add id derivation, forbid same-batch id guessing

[rockymadden]

Problem

uip maestro flow node add generates the node id from --label plus a counter, and has no --id flag. The skill documented this as only "Inserts node into nodes array with a generated id".

With no stated derivation, an agent will hard-code a guessed id in a $vars reference inside the same && chain as the node add that creates the node. The guess is unverifiable at that point, and a wrong one is invisible: flow validate does not check expression correctness, so the flow reports Valid and faults only at runtime.

Observed in the skill-flow-bellevue-weather-simulated coder-eval (weighted score 0.333, gating criterion failed):

• --label 'Normalize Bellevue conditions' → normalizeBellevueConditions1
• decision node, same chain → "expression": "$vars.normalizeConditions1.output.temperatureF > 60"

uip maestro flow validate  → Status: Valid
uip maestro flow debug     → [400302] Error evaluating outgoing flow expression from gateway
                              (edge_warmerThan60F1_true_writeNiceDaySummary1_input)
                             [400302] ... _false_writeJacketSummary1_input
                             [400001] No condition for an outgoing flow was met (warmerThan60F1)

One wrong word. Everything upstream ran clean (trigger, HTTP 200 from open-meteo, normalize script returned real values).

Changes

references/author/editing-operations-cli.md — new ### Generated node IDs section:

• derivation rules and a 4-row example table, plus a scope guard so the section cannot be read as licensing node add for OOTB nodes (rule feat(CodedWorkflows): Add coded workflows plugin #9)
• the counter is always appended, starting at 1
• --label is mandatory in practice: without one the CLI picks its own base name and it is not the type's last segment (core.action.http.v2 → httpRequest1)
• the counter increments against ids already in the file, hand-authored ones included, so the id is not a pure function of the label
• capture recipe (--output-filter "Node.Id", PascalCase)
• the prohibition
• caveat: a digit-leading label produces an id that breaks rule Handle uipcli or rpa-tool instalation at session start #12, and validate accepts it

references/author/greenfield.md — T1 said "capture it from the chained output", which is advice. Now a prohibition: all $vars references belong in T2, written against the ids T1 returned.

SKILL.md rule #11 — extended. The rule already owns "a bare node reference resolves to undefined at runtime"; the wrong-<nodeId> case is its sibling. This matters because the failing agent read SKILL.md in turn 1 and never opened editing-operations-cli.md before authoring — documenting only in the reference file would not have prevented the failure.

+31 / -4 across three files.

Verification

Derivation probed directly against uip 1.202.0, not inferred from the artifact. Every documented example reproduced on a clean flow. Three findings changed what got written:

• No --id flag exists (node add --help), so "capture the id" is the only available guidance.
• The counter is not a pure function of the label. With a hand-authored handMade1 present, --label "Hand made" yields handMade2. An agent that knows the algorithm perfectly still cannot predict the id.
• The response path is Data.Node.Id, PascalCase. --output-filter "Node.id" silently returns Data: [].

Self-review then caught a third: I had written "no label → last dot-segment of the node type", generalized from one coincidental sample (core.logic.merge → merge1). It is wrong — core.action.http.v2 → httpRequest1, core.trigger.scheduled → scheduledTrigger1 — and registry get does not expose the real source, so the doc now states the observed behavior instead of asserting a mechanism. --id also confirmed to fail loudly (unknown option '--id'), not be silently ignored.

Also corrected two claims from an earlier draft: accented letters are dropped, not transliterated (café münchen → cafMNchen1), and Fetch data (v2) → fetchDataV21 (v2 plus counter).

Gates: skills:check-links ✅ · skills:validate ✅ (both flavors) · check-skill-verbs.py ✅ no new findings.

The studioweb flavor replaces greenfield.md's entire project-creation block, so that edit does not reach it — another reason the rule needed to be in SKILL.md and the CLI reference as well. No flavor override required updating.

Out of scope

This is one of several fixes identified from the same eval failure. Deliberately not included:

1. A $vars reference-integrity check in the finalize step. The durable fix, and it belongs in uip maestro flow validate (a dangling $vars.<id> is statically decidable from the file alone) rather than in a skill-authored shell check.
2. The rule feat(CodedWorkflows): Add coded workflows plugin #9 vs rule feat(CI): skill eval and structural validation for uipath-coded-agents #10 tension. Rule feat(CI): skill eval and structural validation for uipath-coded-agents #10 rewards collapsing work into one chained Bash; node add is the only node-CRUD surface that fits a Bash chain, so the batching rule quietly pushes toward the CLI path rule feat(CodedWorkflows): Add coded workflows plugin #9 forbids for OOTB nodes. The eval agent used node add for all seven OOTB nodes despite having read SKILL.md. Worth fixing in the CLI: node add should reject user-owned node types.
3. The author-terminates-at-validate vs graded-on-debug mismatch. The skill forbids flow debug as a validation step, so an agent that follows it cannot self-verify what the grader measures.

🤖 Generated with Claude Code

[github-actions]

Claude finished @rockymadden's task in 2m 11s —— View job

---

PR Review: fix(uipath-maestro-flow): document node add id derivation, forbid same-batch id guessing

• Read review criteria and project conventions
• Read full diff
• Read changed files in full context
• Verify links and cross-references
• Check for secrets/paths/cross-skill deps
• Post review

---

Summary

Documents how uip maestro flow node add generates node IDs from --label (camelCase + counter), and forbids agents from writing $vars.<nodeId> references in the same && chain that creates the node — a guessed ID passes flow validate but faults at runtime. Fix is placed in three locations: SKILL.md rule #11 (read by agents who never open references), the CLI reference (detailed derivation + examples), and the greenfield guide (T1/T2 boundary).

Change-by-Change Review

1. skills/uipath-maestro-flow/references/author/editing-operations-cli.md (+27/-2)

OK

Core of the PR. The new ### Generated node IDs section (lines 40–63) is well-structured:

• Derivation algorithm stated precisely (camelCase, split on non-[A-Za-z0-9], accents dropped, counter always appended starting at 1)
• 5-row example table covering edge cases (accents, parenthesized version suffix, no label) — all verified against uip 1.202.0 per the PR description
• Counter-is-not-pure-function-of-label caveat (handMade1 present → handMade2) correctly warns agents against predicting IDs even with perfect algorithm knowledge
• Prohibition in blockquote with the right failure signature (Cannot read property 'output' of undefined)
• Capture recipe using --output-filter "Node.Id" with PascalCase warning ("Node.id" returns [])
• Digit-leading caveat links to SKILL.md rule Handle uipcli or rpa-tool instalation at session start #12

Line 24: inline note on the existing bullet ("you do not choose it, there is no --id flag") is good early signaling before the agent reaches the full section.

Line 36: --output json description updated from generic to specific (Data.Node.Id (PascalCase)) — eliminates a discovery step.

2. skills/uipath-maestro-flow/references/author/greenfield.md (+3/-1)

OK

Lines 109–111: Replaces vague "capture it from the chained output" advice with a blockquote prohibition: all $vars references belong in T2 against T1's returned IDs. The See [editing-operations-cli.md — Generated node IDs] link keeps this as bridge content pointing to the authoritative section — no duplication of the derivation rules. Good reference-pointer discipline.

3. skills/uipath-maestro-flow/SKILL.md (+1/-1)

OK

Line 98, rule #11: Extended with the prohibition. This is the right placement — the PR description notes the failing agent read SKILL.md in turn 1 and never opened the CLI reference. The addition links to editing-operations-cli.md#generated-node-ids for full detail rather than duplicating derivation rules inline. Rule #11 is getting long, but the token-optimization safety override (§0 of token-optimization.md) explicitly protects rule text from aggressive compression.

What's Missing

Nothing identified. The change is correctly scoped to the documentation gap that caused the observed eval failure. The PR description explicitly lists three related items as out-of-scope with clear rationale for each.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	Existing tests at tests/tasks/uipath-maestro-flow/ cover this skill; this is a documentation-only fix for an observed eval failure, not a new CLI workflow
Skill Body	OK	Rule #11 extension is consistent with existing style; links verified
References & Assets	OK	New section follows naming conventions; all relative links resolve; no cross-skill deps
Repo Hygiene	OK	No secrets, no personal paths, no new skill folder (CODEOWNERS unaffected), changes scoped to single skill

Issues for Manual Review

• The café münchen → cafMNchen1 example implies each dropped accent character acts as a word boundary (the ü between m and n capitalizes the N). The PR states this was verified against uip 1.202.0 — worth confirming this behavior persists across CLI updates, since it's a surprising edge case an agent might encounter with non-English labels.
• The caveat about digit-leading labels (99 bottles → 99Bottles1 passing flow validate despite breaking rule Handle uipcli or rpa-tool instalation at session start #12) is documented but not enforced — flagged as out-of-scope CLI behavior.

Conclusion

Clean PR. The three-location placement (SKILL.md rule, CLI reference, greenfield guide) correctly addresses the failure mode at every level an agent might read. The derivation documentation is precise, example-backed, and verified against the actual CLI. No issues found — approve.

---