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 maintainer workflow with genuine non-obvious wisdom (stale-branch diff traps, squash-merge rebase requirements, maintainer-edit push-back). Its weaknesses are redundancy — the core gotcha is stated three times and the command reference duplicates the workflow — and the absence of any progressive disclosure, with everything in one long file.
Suggestions
Consolidate the 'main..HEAD lies' warning into a single authoritative location (e.g. step 5b) and have the Gotchas and Notes sections cross-reference it instead of restating it, cutting roughly three redundant paragraphs.
Move the project-specific Gotchas (FastAPI route ordering, -weak_framework, cpal::Stream, PyTorch nightly) into a references/past-incident-notes.md file and keep only the triage-generic ones (stale-branch diffs, squash rebase, UNKNOWN mergeable) inline, trimming the main body's token load.
Replace the 'Canonical commands reference' section with pointers to the workflow steps that already contain those commands, or extract it to references/commands.md so the SKILL.md body stays a lean overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — concrete commands with no padding about how git works — but it could be tightened. The 'main..HEAD on a stale branch lies' warning is repeated three times (step 5b, Gotchas, and Notes: 'This is the single most important line in this skill'), and the 'Canonical commands reference' largely duplicates commands already shown in the workflow steps. Several Gotchas entries (FastAPI route ordering, Apple -weak_framework, cpal::Stream !Send, PyTorch nightly) are incident-specific rather than triage-relevant, padding the token budget. This fits the 3 anchor ('mostly efficient but includes some unnecessary explanation or could be tightened') better than 4, given the repetition and off-niche content. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: complete `gh pr list --json` invocations with jq filters, the worktree setup commands, the batch-merge loop with a verification loop, the partial-apply pattern with a heredoc commit message including a Co-Authored-By trailer, and a concrete triage-doc template. This matches the 5 anchor — specific examples cover the common cases end-to-end. | 5 / 5 |
Workflow Clarity | The 11-step workflow is clearly sequenced with explicit validation and feedback loops: the batch-merge loop is followed by a 'Verify afterward that each landed cleanly' check, `mergeable=UNKNOWN` is handled as transient with retry guidance, the triage-doc Progress header and checkboxes act as a resumable checkpoint system, and step 11 gives explicit terminal-status completion criteria. This satisfies the destructive/batch-operation validation requirement and matches the 5 anchor (explicit validation, error-recovery loops, checklists) rather than the 4 anchor, whose 'minor validation gaps' are absent here. | 5 / 5 |
Progressive Disclosure | The file is well-structured with clear section headers, but it is a ~295-line monolith with no reference files at all (no references/, scripts/, or assets/ exist), so there is no progressive disclosure in the literal sense. Content that could live one level deep — the project-specific Gotchas knowledge dump and the duplicated canonical command reference — is fully inlined, matching the 3 anchor ('some structure but could be better organized; content that should be separate is inline') rather than 4, since there are no well-signaled external references at all. | 3 / 5 |
Total | 16 / 20 Passed |