Content
50%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.
The body has a solid skeleton — a quick diagnosis flow, ordering rules with an evidence-only branch, executable CLI/KQL snippets, and a well-signaled service routing table — but execution breaks down in practice: three routing targets are missing from the bundle, the bundled diagnostic scripts are never named, and roughly a fifth of the body is duplicated trigger/link material. All four dimensions land at the 'structure present, key details missing' level.
Suggestions
Fix the broken routing: either add the missing troubleshooting/aks/aks-troubleshooting.md, troubleshooting/compute/vm-troubleshooting.md, and troubleshooting/messaging/README.md files to the bundle or repoint those links to existing references — currently AKS, VM, and Messaging incidents (3 of 6 service areas) dead-end.
Make rule 7 actionable by naming the bundled scripts with paths, e.g. scripts/aks-baseline.sh, scripts/appservice-diagnostics.sh, scripts/containerapp-diagnostics.sh, scripts/pod-evidence.sh, and scripts/test-messaging-connectivity.sh, so 'run the applicable script first' resolves to a concrete command.
Tighten token use: delete the Triggers section (the description's WHEN clause already carries that list), the trailing References list that duplicates the routing table, and the 'AUTHORITATIVE GUIDANCE' blockquote; optionally replace the generic Quick Diagnosis Flow questions with explicit branch points (e.g. 'if resource health is degraded → stop and report platform issue; if healthy → continue to logs') to add the missing validation checkpoints.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core content is efficient (tight CLI blocks, "Quick Diagnosis Flow", no explanations of concepts Claude already knows), but there is real padding: the "AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE" blockquote adds no diagnostic value, the 15-bullet Triggers section duplicates the description's WHEN list, and the trailing References list repeats links already given in the service table and Routing section. Not 2 because the padding is duplication rather than verbose explanation, and the rest is lean. | 3 / 5 |
Actionability | There is genuinely executable guidance ("az monitor app-insights query --apps APP-INSIGHTS -g RG --analytics-query \"traces | where timestamp > ago(1h)…\"", "az containerapp logs show --name APP -g RG --follow"), but rule 7's "run the applicable script first" never names any of the 12 scripts in scripts/, and the routing targets troubleshooting/aks/aks-troubleshooting.md, troubleshooting/compute/vm-troubleshooting.md, and troubleshooting/messaging/README.md do not exist in the bundle, dead-ending 3 of 6 service areas. These are missing key details, not the minor gaps of anchor 4. | 3 / 5 |
Workflow Clarity | "Quick Diagnosis Flow" lays out a clear 5-step sequence ("Identify symptoms → Check resource health → Review logs → Analyze metrics → Investigate recent changes") and rule 2 gives an explicit evidence-only branch ("do not query or modify Azure… identify assumptions and provide optional verification steps"), but each step is a generic question with implicit checkpoints — there is no validation loop or guidance on how to branch based on what resource health or logs reveal. Not 4 because checkpoints are missing/implicit rather than present-with-minor-gaps. | 3 / 5 |
Progressive Disclosure | The overview shape is good — a service table with issue summaries pointing to one-level-deep references/<service>/README.md files that all exist and are clearly signaled — but scored against the actual bundle, 3 of the 8 referenced paths (all three troubleshooting/… links for AKS, VM, and Messaging) are broken, and the 12 diagnostic scripts in scripts/ are never referenced by path anywhere in the body. Navigation works for only half the service areas, which anchor 4's 'minor organization gaps' does not cover. | 3 / 5 |
Total | 12 / 20 Passed |