Content
67%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.
The body is a well-structured, lean router: precise flag parsing, a clear sequence, an explicit fail-closed dispatch protocol, and clearly signaled one-level-deep references. Its main weaknesses are the triple repetition of the routing map across <objective>, <routing>, and <context>, and references that depend on an unresolved template placeholder rather than local bundle files.
Suggestions
Collapse the routing information into the single <routing> table and have <objective> and <context> reference it, removing the duplicated flag-by-flag prose.
State what happens for an unrecognized or malformed flag (e.g., treat as default add-todo argument vs. ask the user) so the parse step has its own validation checkpoint.
Add a fallback for the case where an execution_context path under __GSD_PI_ENGINE_ROOT__ cannot be read (e.g., report the unresolved path and stop), mirroring the fail-closed dispatch handling.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body avoids concept explanations and mostly assumes competence, but the routing information is stated three times: the mode-routing list in <objective> ("default (no flag): Capture as a structured todo ... add-todo workflow"), the <routing> table, and the first-token parsing rules in <context>. This matches 'Mostly efficient but includes some unnecessary explanation or could be tightened'; it is above 2 because nothing explains concepts Claude already knows, and below 4 because consolidating the three routing statements would cut the body substantially. | 3 / 5 |
Actionability | The guidance is concrete and executable for an instruction-only skill: exact flags (--note, --backlog, --seed, --list-seeds, --list), precise parse rules ("strip the flag, pass remainder to note workflow"), the dispatch tool call signature ("call gsd_dispatch with role ... and task"), and explicit file paths to read. This fits 'Mostly executable guidance; concrete code or commands with minor gaps' — it is not 5 because the actual capture mechanics are entirely delegated to the referenced workflow files, which are only listed, not summarized. | 4 / 5 |
Workflow Clarity | The three-step process (parse flag → load and execute workflow → preserve gates) is clearly sequenced, and the dispatch section provides an explicit fail-closed feedback loop ("If gsd_dispatch reports the role unresolved or the child failed, STOP that step and surface the error", with skip-if-optional handling). It matches 'Clear sequence with most checkpoints present; minor validation gaps' — the body delegates validation to the target workflows ("Preserve all workflow gates ... duplicate detection, commits") rather than stating its own checkpoint for, say, unrecognized flags, which keeps it below 5. | 4 / 5 |
Progressive Disclosure | The body is a lean router that puts all detail in one-level-deep references, clearly signaled in a dedicated <execution_context> block listing six workflow files plus ui-brand.md, with explicit instructions to read them. This fits 'Good structure; most content is appropriately placed; references mostly clear; minor organization gaps' — it falls short of 5 because the referenced paths use the unresolved placeholder __GSD_PI_ENGINE_ROOT__ and no local bundle files exist, so navigation depends on an install-time substitution rather than verifiable relative paths. | 4 / 5 |
Total | 15 / 20 Passed |