fix(uipath-rpa): make the report turn one message and chain the output check into the gate

[danmunteanu1]

Why

In a 30-run headless bench of uipath-rpa (5 journeys x 3 replicates x 2 skill arms, Opus 5), the turns spent after the last validate/build were 4-12 per run on every journey and both arms: 60 run/debug calls, 54 shell checks, 46 memory-file Writes, 20 project-context.md writes, 14 AGENTS.md writes plus 9 shell edits of it, and 29 Read/Grep calls back into the skill's own references. Turn-by-turn shape of a typical greenfield XAML run after the gate:

RUN > RUN > RUN > W:project-context > W:AGENTS > W:memory > W:memory > text

Every one of these is a separate assistant message, i.e. a full context replay. Cost tracks message count (~10 s and one replay per message), so this tail was the largest fixed overhead on the short journeys: greenfield XAML took 15-18 messages end to end against the map's 5-turn budget, and 6-8 of the excess were here.

Three causes, all in the map's report row and the memory section:

1. Output verification as its own turns. The T4 row said "check the T3 run's actual outputs", so agents re-ran the workflow and cat/ls/Test-Path'd the result file in separate turns (the --output-filter retries from fix(uipath-rpa): document both run/debug payload shapes (Helm vs Studio Desktop) and drop the --output-filter mandate #3102 added more).
2. Context files written in serial turns. project-context.md, then AGENTS.md, then a shell cat >> AGENTS.md, often preceded by a Grep + Read of environment-setup.md § Project Context Discovery to recover the marker names and the metadata-comment format (29 reference re-reads at wrap-up).
3. Memory saves on runs that qualify nothing. 22 runs updated a memory index plus 24 topic files; the topics were dominated by uip rpa run payload/flag notes (uip-rpa-run-output-filter-null-errors.md, uip-rpa-run-verdict-shape.md) on first-try-clean, card-only builds. The § Cross-session memory rules never said the save happens inside the report message, nor that a clean gate on card-covered activities qualifies nothing.

Fix (docs only)

execution-maps-guide.md:

• Gate rows (greenfield XAML T3, brownfield XAML T3, greenfield coded T3, UIA debug cycle): the chain ends with run --skip-build followed by cat of every file the workflow was asked to write. "The output check is a link of this chain, never its own turn." § Gate ≠ runtime proof updated to match.
• Report rows (T4 in the three journeys, the UIA report turn): "ONE message, no shell calls." Judge the chain's verdict fields and cat output, then emit in the same message as parallel tool calls: Write .claude/rules/project-context.md ∥ Write AGENTS.md ∥ qualifying memory Writes ∥ § Completion Output text. The two facts agents kept re-reading (<!-- discovery-metadata: cs=N xaml=N deps=N --> first line, <!-- PROJECT-CONTEXT:START/END --> markers) are named inline with the pointer to environment-setup.md step 3, and the row states that no Read/Grep precedes these writes because the agent created every file they describe. Brownfield keeps "the discovery agent wrote them in T1 — do not rewrite."
• § Cross-session memory / Save: saves are parallel Writes inside the report message, never one file per turn; "a first-try clean gate on card-covered activities qualifies nothing — skip the save entirely"; uip rpa flag shapes and run/debug payload fields added to Never save (cli-reference.md owns them; a gap there is a /uipath-feedback report).

SKILL.md § Completion Output: the memory-save sentence now says what qualifies (often nothing) and that the saves, the context files and the report text are one message with nothing running after it.

Rule numbering, journey turn numbering (T1-T4), anchors and inbound links are unchanged. No flavor override touches either file.

Expected effect

On the bench data: the report tail collapses from 4-12 messages to 1-2 (the gate chain plus one report message; the UIA journey keeps its window-cleanup turn). Combined with #3102 (which removes the --output-filter retries feeding cause 1 and the memory topics feeding cause 3), greenfield XAML lands at 8-10 messages instead of 15-18.

Follow-up commits from the combined bench

5486c4dd6 — gate rows spell the full run --file-path "<RELATIVE_FILE>" --project-dir "<PROJECT_DIR>" --skip-build --output json (an agent ran run --skip-build without the required --file-path and paid a retry); brownfield report row says not to read, edit or rewrite the discovery-written context files after the gate (staleness is judged by file and dependency counts at the next session, per environment-setup § Project Context Discovery).

a63ff648f — agents/uipath-project-discovery-agent.md: the generated context's Quick Reference named uip rpa run-file and uip rpa get-errors. Both verbs exist but are hidden from --help, so the main agent judged them wrong and spent 4–10 post-gate turns "correcting" the files it had been told not to touch. The template now uses the standard-loop uip rpa run --file-path … / uip rpa validate --file-path …, the header line "Regenerate after significant project changes." is gone (it invited exactly that regeneration), and list-instances --format json became instances list --output json (--format is not a flag of that verb).

Measured on a combined arm (#3055 + #3102 + this PR), 12 runs

--output-filter evaluation failures: 0 of 12 (13 of 15 on main). Memory-file writes: 2 (27 on main), emitted inside the report message. Post-gate turns: 2–6 in 11 of 12 runs (4–17 on main). Greenfield XAML end to end: 9 messages, $1.38–1.47 (main 15–18 messages, $2.36–2.42). Brownfield XAML after a63ff648f: 10 messages, 2-turn tail, zero context-file edits with the discovery agent running. All 12 runs succeeded with correct outputs.

Relationship to other PRs

• fix(uipath-rpa): document both run/debug payload shapes (Helm vs Studio Desktop) and drop the --output-filter mandate #3102 fixes the run/debug payload documentation; independent files.
• fix(uipath-rpa): make Rule 22 a one-turn read so the greenfield map fits its 10-turn gate #3055 renumbers the XAML journeys to T1-T5 and rewrites the T1/T2 rows. It touches the same greenfield/brownfield gate and report rows, so whichever merges second needs a trivial re-anchor (row text here, row numbers there). The content is orthogonal: fix(uipath-rpa): make Rule 22 a one-turn read so the greenfield map fits its 10-turn gate #3055 batches the pre-authoring turns, this PR batches the post-gate turns.

Verification

• node scripts/check-skill-links.mjs: all links resolve. npm run skills:validate: OK.
• Not reproducible in CI (the effect is turn count on a live agent); the measurement above is the 30-run bench, transcripts available on request.

[github-actions]

Claude finished @danmunteanu1's task in 2m 33s —— View job

---

Review of PR #3103

• Read review criteria and project conventions
• Read full diff (HEAD~1...HEAD)
• Read full changed files for surrounding context
• Verify relative links resolve
• Check for cross-skill references, secrets, conventions
• Post review

---

Summary

Documentation-only change to the uipath-rpa skill that collapses post-gate report turns from 4–12 messages into 1–2 by (1) chaining the output check (cat) into the gate Bash chain instead of leaving it as a separate turn, (2) batching the report row's context-file writes, memory saves, and completion text into a single message with parallel tool calls, and (3) qualifying when memory saves are warranted (first-try clean on card-covered activities qualifies none).

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md (line 295)

Severity: OK

Single-line change in § Completion Output. The old text said "save validated patterns … before reporting"; the new text:

• States what qualifies for a save (and that first-try clean on card-covered activities qualifies none).
• Specifies that saves, context files, and report text are one message with parallel Writes — never separate turns.
• Summarizes the shape: output check rides in the gate chain, report message carries everything else, nothing runs after it.

The link to references/execution-maps-guide.md#cross-session-memory is valid. The added text is consistent with the execution-maps changes below. No UIA-boundary violations.

2. skills/uipath-rpa/references/execution-maps-guide.md — § Gate ≠ runtime proof (line 17)

Severity: OK

Reworded from "the report turn checks the actual outputs" to "the gate chain ends with ONE uip rpa run --skip-build followed by a cat of every output file, and the report turn judges what that chain printed." Added "Neither the run nor the output check is its own turn." Consistent with the T3/T4 row changes below.

3. execution-maps-guide.md — Greenfield XAML T3 (line 34)

Severity: OK

T3 now specifies --output-filter with a pointer to cli-reference.md § Capturing the verdict (anchor verified: exists at line 100) and adds && cat of every file the workflow was asked to write. Ends with "The output check is a link of this chain, never its own turn." The --output-filter flag is a generic uip rpa flag (not UIA-coupled), and the pointer follows the correct pattern — names the flag, routes to cli-reference for the shape.

4. execution-maps-guide.md — Greenfield XAML T4 (line 35)

Severity: Low

The most substantive change. T4 is now "ONE message, no shell calls" that emits parallel Writes for project-context.md, AGENTS.md, qualifying memory saves, and the completion text. It inlines the two marker names from environment-setup.md step 3 (and) to avoid the 29 reference re-reads observed in the bench. It correctly points to environment-setup.md step 3 as the authority and notes "you created every file it describes, so no Read/Grep … precedes these writes."

Minor observation: The inlined markers are bridge content (the exact tokens agents need to emit without re-reading the reference) — this is within reference-pointer discipline, since the full contract (read/replace/append logic) stays in environment-setup.md. However, this does create a second place where the marker strings appear. If the markers ever change in environment-setup.md, this row will need updating too. Given the bench data (29 re-reads), the tradeoff is justified — flagging only so it's on the radar.

5. execution-maps-guide.md — Brownfield XAML T3/T4 (lines 50–51)

Severity: OK

Mirrors the greenfield changes. T3 adds --output-filter and cat. T4 says "ONE message, no shell calls" with qualifying memory writes, and correctly notes "Context files were written by the discovery agent in T1 — do not rewrite them" with the brownfield fallback for when the skip gate tripped.

6. execution-maps-guide.md — Greenfield coded T3/T4 (lines 61–62)

Severity: OK

Same pattern as greenfield XAML. T4 says "same shape as the greenfield XAML T4" — DRY cross-reference within the same file, no duplication.

7. execution-maps-guide.md — UIA debug cycle (line 78)

Severity: OK

debug start now includes --output-filter (generic flag, not UIA-coupled). The report is batched into the window-cleanup turn: "in that same message the report — context files, qualifying memory Writes and § Completion Output as parallel calls, as in the greenfield T4." Ends with "The verdict is read from the chain's filtered envelope; never redirect it to a file and parse it in extra turns."

8. execution-maps-guide.md — § Cross-session memory / Save (lines 103, 109)

Severity: OK

Save section now opens with "Emit every qualifying save as a parallel Write inside the report message — never one memory file per turn." Adds the bold qualification: "A first-try clean gate on card-covered activities qualifies nothing — skip the save entirely." Never-save list adds uip rpa flag shapes and run/debug payload fields with the pointer to cli-reference.md.

What's Missing

Nothing identified. The changes are scoped to the two files described in the PR. Rule numbering, journey turn numbering (T1–T4), and anchors are preserved. No flavor override touches either file (confirmed by PR description). Link validation (check-skill-links.mjs) and skills:validate pass per the PR's verification section.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	Documentation-only change to turn-batching instructions; no new CLI workflows or commands introduced — existing tests still cover the same build/validate/run behavior
Skill Body	OK	SKILL.md change is minimal and consistent with execution-maps changes
References & Assets	OK	All relative links verified. New anchors (cli-reference.md#capturing-the-verdict, environment-setup.md step 3) exist. No orphaned files
Repo Hygiene	OK	No secrets, no cross-skill references, no UIA boundary violations, changes scoped to uipath-rpa only

Issues for Manual Review

• Bench validation: The expected effect (report tail collapses from 4–12 messages to 1–2) cannot be verified in CI — it depends on live agent turn behavior. The PR's 30-run bench data supports the change; a follow-up bench after merge would confirm the improvement.
• Interaction with fix(uipath-rpa): document both run/debug payload shapes (Helm vs Studio Desktop) and drop the --output-filter mandate #3102 and fix(uipath-rpa): make Rule 22 a one-turn read so the greenfield map fits its 10-turn gate #3055: The PR notes these are independent but share pointers. Whichever merges second may need a trivial re-anchor. Not a blocker, but the merger should verify links after rebase.

Conclusion

Clean, well-scoped documentation change. Every modification is consistent across the four journey maps and the SKILL.md completion section. Links verified, no UIA boundary violations, no cross-skill coupling. The inlined marker names (Low observation in item 4) are a justified tradeoff given the bench data. Approve.