Content
81%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.
An exceptionally actionable, well-sequenced workflow: every subcommand, flag, refusal code, and validation gate is concrete, and the phase ordering with feedback loops is exemplary for a destructive-adjacent operation. The weaknesses are token efficiency — the hard gates are repeated across three summary sections plus the phases, and design rationale is inlined that the body itself says belongs elsewhere — and a bundle that omits the references/triage.md file the whole skill depends on.
Suggestions
Consolidate the hard gates stated redundantly in "Validation gate (no exceptions)", "Never do these", "Always do these", and inline in the phases into one canonical checklist, and reference it from the phases instead of restating each rule.
Move design-rationale asides (Phase A's lock-ownership mechanics, Phase E's hook-execution security paragraph, Phase F's push-irreversibility rationale) into references/triage.md alongside the other reasoning the body already delegates there.
Ship references/triage.md in the skill bundle — the body routes all judgment calls and the state-record data model to it, so its absence from the bundle leaves the skill's core reasoning unreachable and makes the reference unverifiable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is necessary operational detail rather than concepts Claude already knows, but the same hard gates are stated four times — inline in Phases B/E/F/G, again in "Validation gate (no exceptions)" ("No stage-commit before a validation command has run and reported PASS"), then in "Never do these" ("Never call snapshot more than once per run") and "Always do these" — and phases carry design-rationale asides ("which is what stops one run from releasing another run's active lock"; the hook-execution security paragraph in Phase E) despite the body's own claim that "This file only routes to the helper and states the hard gates; it is not where the reasoning lives." It is not 2 because the verbosity is dense domain-specific guidance, not fluff or padded filler; it is not 4 because the duplication and nested parenthetical run-ons could be cut substantially. | 3 / 5 |
Actionability | Fully executable guidance: the helper invocation template is copy-paste ready ("CLAUDE_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}'; python3 \"$CLAUDE_PLUGIN_ROOT/examples/triage/scripts/triage_helper.py\" <subcommand> [flags]"), every subcommand appears with its complete flag set ("state lock --repo-root \"$REPO_ROOT\" --repo \"$REPO\" --pr <n>"), refusal codes are enumerated with their meanings (PR_READ_UNUSABLE, HEAD_MOVED, PUBLISH_DESTINATION_MISMATCH, ...), and the Report section shows exact output line and table formats. | 5 / 5 |
Workflow Clarity | Phases A through H are explicitly ordered with hard validation checkpoints ("No publish before stage-commit succeeded", "No reply that claims a fix before publish returned matches_pushed_commit: true") and thorough feedback loops for error recovery — e.g. on commit drift "re-inspect the commit and revalidate before Phase F", and on PRESERVATION_FAILED "do not continue to step 3 at all: stop, report the block, and leave the worktree in place for manual recovery". The destructive worktree-cleanup path is gated behind preserve/state write with the ordering spelled out. | 5 / 5 |
Progressive Disclosure | The body cleanly signals a single one-level reference up front ("Read `references/triage.md` before making any judgment call. It holds the evidence-assessment rules, the finding/execution/discussion state model, and the failure-recovery table") and names the helper script path. However, references/triage.md is not present in the provided bundle, so the central reference cannot be verified as a real file, and a substantial amount of reference-worthy detail (error-code semantics, lock-ownership reasoning, hook-disable rationale) is inlined despite the file declaring itself a thin router — anchor 4 (good structure, minor organization gaps) rather than 5. | 4 / 5 |
Total | 17 / 20 Passed |