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.
Excellent agent-facing content: fully executable commands, exact ID semantics with error-message-driven recovery, and well-sequenced recipes with genuine feedback loops. The only real costs are repeated meta-guidance that could be consolidated and reference navigation that relies on CLI commands instead of direct file pointers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational with no explanations of concepts Claude already knows — everything teaches GitButler-specific semantics Claude cannot infer. However, meta-guidance repeats noticeably (`--status-after` in ~8 places, "do not run a verification status" ~5 times) and some passages are sprawling compound sentences (rule 3's integrated-branch logic, the chaining paragraph) that could be consolidated, fitting 4 ("minor instances… that could be trimmed") rather than 5. | 4 / 5 |
Actionability | Fully executable throughout: complete command lines with flags (`but commit -b <branch> -m "<msg>" <id> <id>`), exact ID grammar with valid and invalid examples (`uvw:2e4` vs `uvw:16-40`), quoted error strings ("Unclear where to commit. Found more than one stack"), and exact recovery commands. Copy-paste-ready guidance covers the common cases comprehensively. | 5 / 5 |
Workflow Clarity | Recipes are numbered with explicit checkpoints and feedback loops: the conflict-resolution loop ("Go back to step 1 until it reports no conflicts"), pull's safe-refusal plus `but undo` recovery, dependency-conflict recovery driven by the printed Hint with a fallback re-check, and `but resolve finish` reporting leftover markers and remaining conflicts. Ordering rules ("oldest first", "bottom-up") and chaining-safety conditions make the destructive workflows well-guarded, matching the 5 anchor. | 5 / 5 |
Progressive Disclosure | The bundle's three reference files (references/reference.md, concepts.md, examples.md) are clearly signaled in a dedicated Notes section via `but skill reference` / `but skill concepts` / `but skill examples`, and the body's rules-and-patterns split against the 735-line full reference is reasonable. But references are only reachable via CLI commands rather than file paths, and the 221-line body inlines recipe detail that could partly live in examples.md — "good structure… minor organization gaps" (4) rather than 5's cleanly split overview. | 4 / 5 |
Total | 18 / 20 Passed |