Content
77%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A highly actionable, well-sequenced troubleshooting workflow with genuine validation checkpoints (WhatIf preview, user confirmation, post-retry re-check) and concrete copy-paste commands throughout. The two weaknesses are duplicated overview/detail sections that inflate token cost, and a progressive-disclosure structure whose two most load-bearing reference files (failure-patterns.md, scripts-reference.md) are absent from the bundle, leaving categorization rules and prerequisite install instructions dangling.
Suggestions
Add the missing bundle files failure-patterns.md and scripts-reference.md, or remove/inline their pointers — the body relies on them for the Prerequisites install instructions ("provide installation instructions from scripts-reference.md") and the entire failure-categorization ruleset, so both paths currently dead-end.
Collapse the "## Task" section into "## Implementation Steps" (the two describe the same Phase 1/Phase 2 flow twice) and drop or flesh out Example 2, which only says "[Quick summary as in Example 1]".
Move the Timeline Record Structure section and the detailed snapshot-mismatch detection rules into a reference file to slim the main body to the quick-analysis core.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — commands and rules dominate — but there is real duplication that could be tightened: the "## Task" section (Phase 1/Phase 2 overview) restates the "## Implementation Steps" phases, the "Investigation menu" appears in both Output Format and Example 1, pointers to failure-patterns.md repeat three times, and Example 2 adds almost nothing beyond "[Quick summary as in Example 1]". Not a 4 because the Task/Implementation duplication and near-empty Example 2 are more than 'minor instances of over-explanation'; not a 2 because nothing explains concepts Claude already knows and every section carries actionable information. | 3 / 5 |
Actionability | Fully executable throughout: exact pwsh invocations with parameters ("pwsh -NoProfile -Command \".\tracer\tools\Get-AzureDevOpsBuildAnalysis.ps1 -PullRequest $PR_NUMBER -Verbose\""), concrete snapshot-update commands per OS, a fully worked Example 1 output with real build data, and specific error-handling commands like "gh pr checks <PR> --repo DataDog/dd-trace-dotnet". Copy-paste ready and covering the common cases (no-args, pr, build). | 5 / 5 |
Workflow Clarity | Clear two-phase sequence (quick analysis → ask user → deep analysis only on request) with numbered steps, and the risky batch operation (retrying failed stages) has explicit validation checkpoints: preview with "-WhatIf" first, "Confirm with user", then run, plus "optionally re-check status" as a feedback loop. The Error Handling section (Build Not Found, Logs Too Large, Rate Limiting) provides recovery branches, matching the anchor-5 pattern. | 5 / 5 |
Progressive Disclosure | Signaling is excellent — the "Additional Resources" section gates each reference precisely ("Load ONLY during Phase 2 categorization", "Load ONLY if the PowerShell script fails", "Load ONLY if bypassing the PowerShell script") and references are one level deep. But scored against the actual bundle: of the three referenced files, only references/cli-reference.md exists — failure-patterns.md and scripts-reference.md (referenced five-plus times, including the Prerequisites install instructions and the core categorization rules) are missing, so the primary disclosure paths are broken. Not a 2 because the in-body structure and existing reference are well organized; not a 4 because two of three referenced paths do not resolve. | 3 / 5 |
Total | 16 / 20 Passed |