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 well-structured orchestration skill: the two-phase workflow with an explicit approval gate, executable shep command examples covering the common wave patterns, and appropriately pushed-out reference files. The main issues are a missing referenced file (`templates/workstream-plan.md` does not exist in the bundle), some repetition between the mechanics section and the anti-patterns list, and inline CLI semantics that duplicate the cli-reference.
Suggestions
Add the referenced `templates/workstream-plan.md` to the bundle (or drop the reference) — Phase 1 Step 4 tells the agent to use it, but the file does not exist, so the agent cannot follow the instruction.
Consolidate the redundancy between the '--parent' mechanics paragraph and the anti-patterns list ('Everything parented to everything' / 'Hand-rolled git worktree add' restate points already made in 'The mechanics that matter'), trimming roughly a paragraph of tokens.
Consider moving the detailed '--parent' auto-rebase/unblocking semantics to `references/cli-reference.md` and keeping only the decision table inline, since the body already directs the reader there before composing commands.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, shep-specific guidance (parent/auto-rebase semantics, file-ownership partitioning rule, staged waves) and avoids explaining concepts Claude already knows, but there is noticeable redundancy: '--parent is not a substitute for good partitioning' reappears as the 'Everything parented to everything' and 'Hand-rolled git worktree add' anti-patterns, and the two-phase separation is stated three times. It sits between the level-3 'could be tightened' and level-5 'every token earns its place' anchors — efficient with minor trims available, i.e. level 4. | 4 / 5 |
Actionability | The bash examples are copy-paste ready apart from unavoidable placeholder ids: full 'shep feat new ... --repo ... --attach ... --push --pr' invocations for the foundation, dependent, independent, and capacity-staged cases, plus a complete monitoring command block ('shep feat ls / show / logs / approve / reject / resume') and a decision table mapping each dependency situation to a mechanism. The examples cover the common cases exactly as the level-5 anchor requires. | 5 / 5 |
Workflow Clarity | The two phases are hard-separated with an explicit validation gate ('Do not create a single feature until Phase 1 is written down and the user has approved it'), Phase 1 is a numbered five-step sequence ending in 'Stop and get approval', and Phase 2 includes a feedback loop ('After each merge, re-check `shep feat ls`', plus reject/resume handling for failed features) and a decision table for choosing the dependency mechanism. This matches the level-5 anchor of a clear sequence with explicit validation steps and feedback loops; level 4 would have missing checkpoints, which is not the case here. | 5 / 5 |
Progressive Disclosure | Structure is good: the deep material (full partitioning rubric, full CLI flag reference, PM/work-item commands) is pushed to `references/partitioning.md` and `references/cli-reference.md`, both real bundle files, clearly signaled with when to read them ('Read it before composing commands'), and one level deep. However, the body instructs 'Use `templates/workstream-plan.md`' and no such file exists in the bundle — a broken reference — and the long '--parent' auto-rebase mechanics paragraph duplicates cli-reference material. Good structure with a concrete organization gap places it at level 4 rather than 5. | 4 / 5 |
Total | 18 / 20 Passed |