Content
88%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 strong, highly operational workflow document: every step has executable commands, explicit gates, validation with evidence requirements, and maintainer checkpoints, with no filler. The only detractors are duplicated warnings and an entirely inlined structure with no reference split.
Suggestions
State the fork-remote `gh` caution once (e.g. in a short 'Conventions' note near the top) and reference it from steps 1 and 2, rather than repeating it verbatim in both; do the same for the 'never use the host's Create PR action' warning shared by steps 5 and 6.
Move the ordered PR-body template and the record-format field summary (Behavior/Trace/Likely files/Validation) into a single reference file (e.g. references/pr-body.md) linked from step 6, slimming SKILL.md toward an overview while keeping detail one level deep.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and high-signal with no basic-concept explanations (it assumes competence throughout, e.g. going straight to "git remote -v must list microsoft/vscode"), but two warnings are repeated nearly verbatim — the fork-remote `gh` caution appears in both step 1 ("never bare `gh issue view`, which a fork remote can redirect") and step 2 ("never rely on `gh`'s default-repo resolution, which a fork remote can redirect…"), and "never hand off to a host's Create PR action" appears in both step 5 and step 6. This matches anchor 4 (minor instances that could be trimmed) rather than 5, and exceeds anchor 3 since there is no evaluative filler or unnecessary explanation. | 4 / 5 |
Actionability | Guidance is copy-paste executable at every step: the record fetch (`gh api "repos/egamma/vscodesweeper-state/contents/records/microsoft/vscode/items/<issue-number>.md?ref=state"…`), the live gate (`gh issue view <issue-number> --repo microsoft/vscode --json state,labels,updatedAt`), the PR-open command (`gh pr create --repo microsoft/vscode --base main --draft --title … --body-file <body file>`), exact plan paths (`.sweeper/plans/issue-<issue-number>.md`), and a fully ordered PR-body spec. The common cases (both modes, refusal paths) are all covered; the one abstraction ("a normal, descriptive message") is a deliberate delegation, matching anchor 5. | 5 / 5 |
Workflow Clarity | The process is explicitly sequenced (steps 0–6) with validation checkpoints everywhere: five numbered refusal gates, a staleness check, a statement-by-statement validation table in step 5, tests required to "fail before your change and pass after — run them both ways", gates 2–4 re-run before any push, and explicit error-recovery paths (no record → "continue on the issue by your normal means"; dirty tree → stop without stashing). This is anchor 5 — clear sequence, explicit validation, feedback loops, and checklists; the destructive/public-operation cap does not apply since validation is pervasive. | 5 / 5 |
Progressive Disclosure | No bundle files exist, and the ~120-line body is well sectioned with numbered headings so everything operationally needed is inline and navigable — good structure per anchor 4. It falls short of anchor 5 because nothing is split out: the document exceeds the "under 50 lines" simple-skill exception and inlines the full PR-body template and record-format details that could live in a one-level-deep reference. | 4 / 5 |
Total | 18 / 20 Passed |