docs(uipath-maestro-flow): refresh validate error quality

[tmatup]

Summary

Two documentation-fidelity updates so the uipath-maestro-flow skill stops describing pre-fix uip maestro flow validate behaviour. Pairs with:

• flow-workbench #1479 — adds structured parseIssues + JSON parse line:col
• cli #1896 — emits one issue per Zod issue with the real path; adds shape hints on connector configuration errors

Changes

1. sourceHandle/sourcePort and targetPort "vague root error" wording

editing-operations-json.md and file-format.md previously told the agent that writing sourceHandle instead of sourcePort (or omitting targetPort) produces a "vague root-level error Invalid input: expected string, received undefined". Post-fix the validator returns the precise edge path:

[error] [edges[N].sourcePort] expected string, received undefined

The gotchas are rewritten to describe what the agent will actually see, and reinforce that the path identifies the offending edge entry exactly.

2. failure-modes.md — "validate passes, debug faults" list

The connector inputs.detail (missing essentialConfiguration block) family was incorrectly listed as a debug-only fault. The IS SDK's validateConfiguration rule has always caught the structural cases (empty configuration, missing envelope, invalid JSON) at validate time; cli #1896 additionally appends shape hints pointing at uip maestro flow node configure.

Reorganized the section so the "validate doesn't catch" list contains only items that genuinely manifest at debug time, plus a new "structural rules do catch (validate exits non-zero, with a shape hint)" subsection covering the connector configuration family. Agents that see one of those titles should now look at the validate output, not flow debug.

Test plan

• Visual diff of the three files — wording aligned with the actual messages cli #1896 will emit.
• No code changes; no CI hooks beyond markdown linting.

🤖 Generated with Claude Code

[github-actions]

Claude finished @tmatup's task in 1m 31s —— View job

---

PR Review: docs(uipath-maestro-flow): refresh validate error quality

• Gather context (review criteria, full diff, changed files)
• Check structure and conventions
• Verify relative links resolve
• Check for cross-skill references, secrets, personal paths
• Post review findings

---

Summary

Updates three uipath-maestro-flow reference files to align error message descriptions with post-fix CLI behavior (cli #1896, flow-workbench #1479). The validator now returns precise edge paths ([edges[N].sourcePort]) instead of vague root errors, and connector configuration structural checks are correctly categorized as validate-time (not debug-only) faults.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/author/references/editing-operations-json.md

Severity: OK

Line 33: Replaces the "vague root error" description for sourceHandle misuse with the precise path-based error message [error] [edges[N].sourcePort] Invalid input: expected string, received undefined. Accurate, and the parenthetical explaining what the path tells the agent is helpful.

2. skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md

Severity: OK

Lines 209–223: Correctly moves the connector inputs.detail configuration family out of the "validate doesn't catch" list and into a new subsection describing what the structural rules do catch at validate time. The three cases (missing/empty configuration, missing essentialConfiguration envelope, invalid JSON in =jsonString:) are clearly listed. The guidance to re-run uip maestro flow node configure is actionable.

3. skills/uipath-maestro-flow/references/shared/file-format.md

Severity: OK

Lines 205–207: Updates both gotchas — edges.N.targetPort → edges[N].targetPort (bracket notation matching actual output), and the sourceHandle gotcha now shows the precise path instead of "vague root-level error." Consistent with the editing-operations-json.md changes.

4. Minor inconsistency (pre-existing)

Severity: Low

editing-operations-json.md:33 quotes the error as Invalid input: expected string, received undefined (with the "Invalid input:" Zod prefix), while file-format.md:205-207 quotes it as just expected string, received undefined (without the prefix). This predates this PR — the file-format.md wording was already missing the prefix before these changes. Not blocking, but worth harmonizing in a future pass so agents pattern-match consistently across files.

What's Missing

Nothing identified. This is a scoped documentation-fidelity update with no new CLI workflows or capabilities that would need test coverage.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Not touched — no changes needed
E2E Tests	OK	Doc-only change; no new CLI workflows introduced
Skill Body	OK	Not touched
References & Assets	OK	All three changed files are accurate and internally consistent
Repo Hygiene	OK	No cross-skill refs, no secrets, no personal paths, changes scoped to one skill

Issues for Manual Review

• Verify the exact error message format emitted by cli #1896 matches what's documented (specifically whether the Invalid input: prefix is present in the [edges[N].*] messages — this reviewer cannot run the CLI to confirm).

Conclusion

Clean, well-scoped PR. All three changes correctly align documentation with the new structured error output from the validator. No issues found that would block merge.

[tmatup]

Review Response

1. editing-operations-json.md:33 — sourceHandle/sourcePort gotcha

No change required — bot rated OK. The new wording precisely describes what the validator now emits post-cli #1896.

2. failure-modes.md:209-223 — connector configuration moved out of "validate doesn't catch"

No change required — bot rated OK. The structural rules subsection correctly enumerates the three cases the IS SDK already catches at validate time.

3. file-format.md:205-207 — bracket-notation harmonization

No change required — bot rated OK on the bracket fix.

4. Minor inconsistency: Invalid input: prefix missing from file-format.md — Severity: Low

Fixed in cde8f5f. Both gotchas in file-format.md now include the Invalid input: prefix, matching the actual Zod 4 runtime output and the wording in editing-operations-json.md:33. This was a pre-existing inconsistency the bot flagged as worth harmonizing — single-line change, landed in this PR rather than deferred.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com