feat(case-tool): add troubleshooting step for failed cases

[charlesliu9]

Adds references/troubleshooting-guide.md covering the diagnostic priority
(incidents → variables → caseplan correlation → traces) and the CLI
reference for uip maestro case instance, incident, and job. Links
the guide from SKILL.md's reference table and from implementation.md's
Step 14a.

[github-actions]

Claude finished @charlesliu9's task in 2m 0s —— View job

---

PR Review: feat(case-tool): add troubleshooting step for failed cases

• Gather context and read review criteria
• Read full diff and changed files
• Check existing PR conversation
• Validate skill structure and conventions
• Verify links and cross-references
• Check for secrets/tokens/paths
• Post review findings

---

Summary

Adds references/troubleshooting-guide.md with a diagnostic workflow (incidents → variables → caseplan correlation → traces) and CLI reference for instance, incident, and job subcommands. Links the guide from SKILL.md's reference table and from implementation.md's new Step 14a.

Change-by-Change Review

1. skills/uipath-maestro-case/references/implementation.md — Lines 227–229

Severity: High — broken relative link

The new Step 14a links to references/troubleshooting-guide.md:

read **[references/troubleshooting-guide.md](references/troubleshooting-guide.md)**

Since implementation.md is already inside references/, this resolves to references/references/troubleshooting-guide.md — which does not exist. Every other link in this file uses same-directory relative paths (e.g., planning.md, skeleton-tasks.md, case-editing-operations.md).

Fix: Change the link to [troubleshooting-guide.md](troubleshooting-guide.md).

Fix this →

2. skills/uipath-maestro-case/references/troubleshooting-guide.md — Lines 94–143

Severity: Medium — Reference Pointer Discipline violation

The "CLI command reference" section (lines 94–143, ~50 lines) duplicates content already in case-commands.md. Every command listed — instance list/get/incidents/variables/asset/cursors/element-executions, incident summary/get, job status/traces plus all lifecycle commands — already exists in case-commands.md (lines 301–410). The only differences are cosmetic (adding --output json flags, using -f shorthand).

Per the repo's reference pointer discipline: when a section links to or restates another reference doc's content, it should contain only bridge content. The diagnostic workflow (Steps 1–5) is valuable and unique. The CLI reference section should be replaced with a pointer to case-commands.md.

Fix: Replace the CLI command reference section (lines 94–143) with a bridge pointer, e.g.:

## CLI command reference

Full flag details and options for all commands above: [case-commands.md](case-commands.md) §§ `uip maestro case instance`, `uip maestro case incident`, `uip maestro case job`.

Fix this →

3. skills/uipath-maestro-case/SKILL.md — Line 87

Severity: OK

New row in the Reference Navigation table. Link resolves correctly (references/troubleshooting-guide.md from SKILL.md's location). Placement is logical — after the CLI commands row and before registry discovery.

4. skills/uipath-maestro-case/references/troubleshooting-guide.md — Diagnostic workflow (Lines 1–91)

Severity: OK

The diagnostic steps (1–5) are well-structured, prescriptive, and follow repo conventions: --output json on all parsed commands, <UPPER_SNAKE_CASE> placeholders, numbered steps, clear stop condition ("stop when you have enough to diagnose the root cause"). The callout about --folder-key being required for incident get is a useful non-obvious constraint.

What's Missing

• No error handling guidance. The guide doesn't specify what an agent should do if a command fails (e.g., instance incidents returns empty, or the instance ID is invalid). Adding a brief "if no incidents returned, skip to Step 3" or similar branching logic would improve LLM usability.
• No retry/stop conditions. Unlike other parts of this skill (e.g., Step 12's 3-retry policy), there's no max retry or escalation path if troubleshooting is inconclusive after all 5 steps.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	Not applicable — no new CLI workflows or capabilities, existing tests unaffected
Skill Body	Issue	Broken link in implementation.md (High)
References & Assets	Issue	CLI reference duplication with case-commands.md (Medium)
Repo Hygiene	OK	CODEOWNERS already covers path, no secrets, changes scoped to skill

Issues for Manual Review

• CLI command accuracy: Cannot verify whether the CLI commands (especially uip maestro case instance subcommands and their flags) match the actual tool API. The commands appear consistent with case-commands.md, but domain-specific correctness requires manual verification.
• --folder-key auto-detection claim: The guide states most instance subcommands auto-detect the folder key when omitted but incident get requires it explicitly. This behavioral distinction should be verified against the actual CLI.

Conclusion

The diagnostic workflow itself is a solid addition. Two issues need fixing before merge:

1. (High) Broken relative link in implementation.md — references/troubleshooting-guide.md → troubleshooting-guide.md
2. (Medium) ~50 lines of CLI command reference duplicated from case-commands.md — replace with a bridge pointer

---