fix(docs): HITL outcome ports were documented as a single completed handle

[dushyant-uipath]

Problem

QuickForm HITL nodes wire one outcome-<outcome.id> port per outcome. The docs taught a single completed handle regardless of outcome count, so an agent following them left every non-default outcome unwired.

Fixed

• 8 uipath-maestro-flow references taught completed unconditionally: corrected to per-outcome outcome-<id> ports.
• Sibling uipath-human-in-the-loop skill contradicted the fix (SKILL.md, hitl-node-quickform.md, hitl-node-apptask.md): corrected.
• A coded-action-app example flipped onto outcome-derived ports by gaining an inputs.schema block it shouldn't have had: the block is removed, port stays the static completed for that node type.
• impl.md and planning.md claimed outcome-completed never reappears once outcomes exist: corrected. It is the zero-outcome placeholder, or the port for a real outcome whose own id happens to be completed.

Docs only, no executable surface changed.

Split from #3180

Split out of #3180 into three, so documentation wording, checker logic, and task fixtures each get their own reviewable diff: docs here, checker logic in #3260, task fixture migration in #3261 (depends on #3260). #3180 is closed in favor of these three.

🤖 Generated with Claude Code

[github-actions]

Claude finished @dushyant-uipath's task in 2m 53s —— View job

---

PR Review: fix(docs): HITL outcome ports were documented as a single completed handle

• Read review criteria and project conventions
• Read full diff (11 files, +50/−38)
• Read all changed files in full context
• Verify relative links resolve
• Check for cross-skill references and secrets
• Post review findings

---

Summary

Corrects the HITL QuickForm port wording across both uipath-maestro-flow (8 references) and uipath-human-in-the-loop (3 files). Previously all docs taught a single completed handle regardless of outcome count; now they correctly document per-outcome outcome-<outcome.id> ports. Also removes a spurious inputs.schema block from the coded-action-app example that would have flipped an app-based node onto the wrong port mode, and adds a new debug row for the common misconfiguration of wiring outcome-completed as a shared exit.

Change-by-Change Review

1. skills/uipath-human-in-the-loop/SKILL.md — Critical Rules 2–3

Severity: OK

Rule 2 correctly replaces the single-completed instruction with per-outcome wiring, calls out the app-based exception, and warns against adding inputs.schema to an app-based node. Rule 3's definition entry wording is generalized from "completed handle" to "handles" — consistent with the new model. Good, clear rewrite.

2. skills/uipath-human-in-the-loop/references/hitl-node-apptask.md

Severity: OK

Intro line now explicitly contrasts the static completed port with QuickForm's outcome-<outcome.id> ports, and adds the inputs.schema anti-pattern warning. Edge Wiring section correctly says "Unlike QuickForm" instead of "Identical to QuickForm." Accurate.

3. skills/uipath-human-in-the-loop/references/hitl-node-quickform.md

Severity: OK

Edge Wiring section updated with two-outcome JSON example (outcome-approve, outcome-reject). New table row documents outcome id conversion rules with examples, and explicitly ties the id to the wiring port. The "Wire every outcome's port" callout clearly explains the outcome-completed placeholder semantics. Well done.

4. skills/uipath-maestro-flow/references/author/brownfield.md

Severity: OK

One-line table cell update: completed → outcome-<outcome.id>. Clean.

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

Severity: OK

Operation matrix row updated with per-outcome wording and a pointer to hitl/impl.md. Clean.

6. skills/uipath-maestro-flow/references/author/planning-arch.md

Severity: OK

Port table cell changed from completed to free-form text with a link. Breaks the table's compact pattern slightly, but the information is necessary — the port is not a simple static name. Acceptable.

7. skills/uipath-maestro-flow/references/author/plugins/hitl/impl.md

Severity: Low

Major rewrite: removes the inputs.schema block from the coded-action-app example (lines 127–130 removed), adds rules explaining why it shouldn't be there, updates the common pattern to show outcome-based branching, adds a new debug row for the outcome-completed misuse case. All changes are technically correct and well-motivated.

• Missing trailing newline (impl.md:181): the file ends without a newline (visible in the diff as \ No newline at end of file). This is a pre-existing issue — no newline before or after this PR — but since the last line was modified, this would be a good time to fix it.

8. skills/uipath-maestro-flow/references/author/plugins/hitl/planning.md

Severity: OK

Ports table changed from single row to per-outcome explanation. Wiring pattern and topology examples updated with outcome-based branching. New guidance on not inserting a Decision node after HITL (the outcome handles already are the branch points). The outcome-completed blockquote explanation is thorough and consistent with the same explanation in impl.md and quickform.md.

9. skills/uipath-maestro-flow/references/diagnose/CAPABILITY.md

Severity: OK

Anchor link updated from #hitl-completed-port-unwired to #hitl-outcome-port-unwired to match the renamed section in failure-modes.md. Verified the anchor resolves.

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

Severity: OK

Section heading, TOC entry, symptom, cause, fix, and two internal cross-references all updated from completed to outcome-port semantics. Consistent throughout.

11. skills/uipath-maestro-flow/references/shared/cli-commands.md

Severity: OK

Post-hitl add instruction updated. Clean.

What's Missing

• Missing trailing newline in impl.md (Low): file ends without \n — pre-existing, but the last line was touched. Fix this →
• Nothing else identified — coverage across the two skills is thorough and consistent.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Not touched; no issues
E2E Tests	OK	Docs-only change; no new CLI workflows or commands introduced
Skill Body	OK	Critical Rules updated correctly in both skills
References & Assets	OK	All 8 maestro-flow references + 2 HITL references updated consistently; all relative links verified; anchor references resolve
Repo Hygiene	OK	No secrets, no new skills, no cross-skill structural deps (existing doc-context links are pre-existing and properly marked)

Issues for Manual Review

• Domain accuracy: The per-outcome port semantics (outcome-<outcome.id> vs. static completed for app-based nodes) are a domain-specific claim about the Maestro Flow runtime. A reviewer with platform knowledge should confirm these semantics match the actual runtime behavior.
• outcome-completed edge case: The docs now state that outcome-completed is both the zero-outcome placeholder AND a valid port when an outcome's id is literally completed. This dual role is clearly documented but could still confuse agents — worth a domain expert sanity check.

Conclusion

Clean, well-scoped docs-only PR. All 11 files are internally consistent, all links resolve, and the old completed wording has been comprehensively replaced with per-outcome port semantics. The only nitpick is a missing trailing newline in impl.md (pre-existing, Low severity). Approve.
|

[dushyant-uipath]

Closing. Reconsolidated back into #3180 as a single PR.