feat(uipath-maestro-flow): port the bpmn reasoning-budget / working-style preamble

[rockymadden]

What

Adds the # Reasoning budget / # Working style preamble above the # UiPath Flow Skill heading, porting what uipath-maestro-bpmn/SKILL.md has carried since #2622.

+15 lines on an always-loaded file, roughly 500 tokens. That is the cost side of the trade-off; the benefit is below.

Why

The numbered rules cover facts (shapes, flags, ownership). The failures the Flow evals keep surfacing are habits that no single rule owns:

• Re-running a command that already answered, to reshape its output (the 2026-09-02 skill-flow-slack-weather-pipeline failure, addressed narrowly in fix(uipath-maestro-flow): stop re-running a completed flow debug to reshape output #3002).
• Re-querying the registry once per field instead of dumping a node type's schema once.
• Issuing CLI calls turn-by-turn when rule feat(CI): skill eval and structural validation for uipath-coded-agents #10 already asks for them chained.
• Hand-deriving layout and connector detail that format and node configure emit.

Each has a rule or an anti-pattern somewhere. None of them has a stated working style that makes the habit the default before the agent reaches the specific rule. That is what this preamble is for, and it is the same reason maestro-bpmn got one.

Adaptations from the bpmn original

• "Run the shipped script" becomes "run the uip verb." maestro-bpmn ships scripts; Flow's mechanical work is CLI verbs, so the bullet names them: node configure detail and bindings[], format layout, registry get node shapes. Same principle, correct mechanism.
• Deep reasoning points at Flow's actual hard calls rather than a generic "one hard judgment": node-type selection (the external-service ladder), topology, and cross-node data flow. Those are the three the evals keep catching.
• Bullets defer to the numbered rules instead of restating them. feat(EvalsBreakdown): break down eval skill #1 for output filters, feat(CodedWorkflows): Add coded workflows plugin #9 for CLI vs ad-hoc scripting, feat(CI): skill eval and structural validation for uipath-coded-agents #10 for chaining. One maintenance site per fact, so the "3 turns" count stays only in rule feat(CI): skill eval and structural validation for uipath-coded-agents #10.
• "Write code once and reuse" becomes "prefer the CLI to ad-hoc code." The bpmn version encourages writing scripts. Here rule feat(CodedWorkflows): Add coded workflows plugin #9 makes scripting a last resort needing user approval, so the bullet leads with that and keeps the write-once advice for when code is genuinely warranted.
• Keep-outputs-small names its candidates. flow debug, job traces, and registry get are the payloads worth redirecting to a file outside the solution tree. Filtering covers "I know the fields"; capture covers "slow, side-effecting, or unrepeatable", so re-reading never means re-running. > /tmp/*.json matches existing precedent in uipath-admin, uipath-coded-apps, and Flow's own inline-agent/impl.md.
• Tightened to terse mode per .claude/rules/token-optimization.md.

Notes for review

• The block sits outside every flavor marker, so all flavors inherit it. The studioweb flavor already inherits rules feat(EvalsBreakdown): break down eval skill #1/feat(CodedWorkflows): Add coded workflows plugin #9/feat(CI): skill eval and structural validation for uipath-coded-agents #10 unchanged and overrides only project creation and upload scope, so nothing here contradicts it. Worth a second opinion if a Studio-Web-tool-driven agent should not be pointed at uip verbs.
• check-uip-commands.sh only scans fenced code blocks, so inline commands in prose are unverified by it. Both inline commands here are fully qualified by hand.
• Checks: .maintenance/check-all.sh 9/9, npm run skills:validate, npm run skills:check-links.

🤖 Generated with Claude Code

[github-actions]

Claude finished @rockymadden's task in 1m 42s —— View job

---

PR Review: feat(uipath-maestro-flow): add reasoning-budget / working-style preamble

• Gather context (read review criteria, CLAUDE.md, skill-review rules)
• Read full diff and changed files
• Read existing PR conversation
• Perform skill-specific checks
• Verify rule references (feat(EvalsBreakdown): break down eval skill #1, feat(CodedWorkflows): Add coded workflows plugin #9, feat(CI): skill eval and structural validation for uipath-coded-agents #10) resolve correctly
• Verify preamble sits outside all flavor markers
• Post review findings

---

Summary

Adds a # Reasoning budget / # Working style preamble to skills/uipath-maestro-flow/SKILL.md, matching the pattern established in uipath-maestro-bpmn/SKILL.md (#2622). The new content is well-adapted to Flow's CLI-verb-driven workflow (vs. bpmn's script-driven model) and correctly defers to the numbered Critical Rules rather than restating them.

Change-by-Change Review

1. skills/uipath-maestro-flow/SKILL.md (+15/−0)

Severity: OK

The 15 added lines insert two new #-level sections (# Reasoning budget, # Working style) above the existing # UiPath Flow Skill heading. Verified:

• Rule references are valid. rule #1 → line 89 (--output json / --output-filter), rule #9 → line 111 (node ownership / scripting last resort), rule #10 → line 112 (three-turn batching). All resolve correctly.
• Flavor safety. The preamble sits above all `` markers (first marker is line 30). The studioweb flavor override (skill-flavors/studioweb/uipath-maestro-flow/SKILL.md) only replaces flavor-marked blocks, so all flavors inherit the preamble unchanged. No contradictions with studioweb's overrides.
• Adapted correctly from bpmn. "Run the shipped script" → "run the uip verb" is the right translation (maestro-flow's mechanical work is CLI verbs, not scripts). "Write code once and reuse" is correctly reframed as "Prefer the CLI to ad-hoc code" per rule feat(CodedWorkflows): Add coded workflows plugin #9's scripting-last-resort stance. Deep reasoning targets are narrowed to the three specific hard calls (node-type selection, topology, cross-node data flow) rather than bpmn's generic "one hard judgment."
• Prose quality. Terse, prescriptive, consistent with .claude/rules/token-optimization.md. No hedging, no filler.
• No secrets, tokens, or personal paths. Clean.
• No cross-skill dependencies. Self-contained — references only this skill's own CLI verbs and rules.
• Heading hierarchy. # Reasoning budget → # Working style → # UiPath Flow Skill — all at h1, consistent with the bpmn skill's structure and the existing # UiPath Flow Skill heading.

What's Missing

Nothing identified. This is a targeted, well-scoped addition. No new CLI workflows or capabilities are introduced, so no test updates are needed.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Unchanged, valid
E2E Tests	OK	No new testable behavior — preamble is agent guidance, not a new workflow
Skill Body	OK	Clean insertion, correct rule references, well-adapted from bpmn source
References & Assets	OK	No references changed
Repo Hygiene	OK	No secrets, no cross-skill deps, scoped to one file

Issues for Manual Review

None found. The preamble's behavioral guidance (e.g., "A greenfield build is three turns, not ten") aligns with the existing Critical Rules and greenfield reference. Domain accuracy of the three deep-reasoning targets (node-type selection, topology, cross-node data flow) is a judgment call for the skill author — the eval data cited in the PR description supports these choices.

Conclusion

Clean, well-scoped PR. The preamble is correctly adapted from the bpmn precedent, all rule references resolve, flavor inheritance is safe, and prose follows the repo's token-optimization conventions. No issues found — approve.

---

[Copilot]

🟢 Approval recommended

The change is a small, self-contained documentation update that aligns with existing Flow rules (#1/#9/#10) and established patterns already used elsewhere in the repository.

Pull request overview

Adds a short “Reasoning budget” and “Working style” preamble to the always-loaded uipath-maestro-flow skill contract, mirroring the successful pattern previously introduced in uipath-maestro-bpmn. The intent is to nudge agents toward CLI-first, batched execution habits that reduce redundant tool calls and output bloat during Flow authoring/operate/diagnose workflows.

Changes:

• Inserted # Reasoning budget section to distinguish when to act mechanically via uip verbs vs when to spend deeper reasoning on Flow design judgments.
• Inserted # Working style section to reinforce whole-path planning, de-duplication of work, and output-size control (including redirect-to-file patterns for large/side-effecting outputs).

File summaries

File	Description
skills/uipath-maestro-flow/SKILL.md	Adds a reasoning/working-style preamble above the main skill heading to promote CLI-first, batched, non-redundant execution habits.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.