Content
62%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 actual design-shotgun workflow (Steps 0–6) is excellent — concrete, executable, and rich with validation and feedback loops — but it is buried in ~300 lines of generic gstack framework boilerplate that doubles the file's token cost. The undefined `$GSTACK_DESIGN` variable and zsh-only shell fragments are minor executable gaps. Structure is monolithic with no progressive disclosure of the shared framework material.
Suggestions
Extract the shared framework content (Voice persona, Completeness Principle/Boil the Lake, telemetry and proactive onboarding flows, AskUserQuestion format, Contributor Mode, Completion Status Protocol, Plan Status Footer) into a common base file or shared reference the skill points to, cutting the body roughly in half — this addresses both conciseness and progressive disclosure.
Define GSTACK_DESIGN in the preamble (mirroring GSTACK_BROWSE) so the DESIGN SETUP fallback `$D=$GSTACK_DESIGN/design` doesn't resolve to an empty path, and guard or remove the zsh-only `setopt +o nomatch` / `source <(...)` lines so the bash blocks run under bash.
Merge Step 4's inline feedback-confirmation summary with Step 5, which repeats the same 'Here's what I understood' output and AskUserQuestion verification, removing a duplicated section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly 300 of the ~710 body lines are generic framework boilerplate unrelated to design exploration — a full "Voice" persona section (~40 lines), "Boil the Lake" essay promotion, telemetry/proactive onboarding dialogs, an effort-compression table, contributor mode, and a plan-footer protocol — all auto-generated shared scaffolding that pads every token of context. This is "noticeably verbose; several unnecessary explanations or padded sections" (2-anchor); it exceeds the 3-anchor's "some unnecessary explanation" since the padding is systematic and comprises nearly half the file. | 2 / 5 |
Actionability | The design-shotgun steps are highly concrete: exact bash setup blocks, the full `$D` command list, a complete copy-paste agent prompt template with retry rules, a polling loop, and the feedback JSON shape. It falls short of fully executable (5-anchor) due to real gaps: `$D=$GSTACK_DESIGN/design` references `$GSTACK_DESIGN`, which is never defined in the preamble (only `GSTACK_BROWSE` is), and zsh-only `setopt +o nomatch` / `source <(...)` lines appear inside otherwise bash-targeted blocks. | 4 / 5 |
Workflow Clarity | Steps 0–6 are clearly sequenced with explicit validation checkpoints and error-recovery loops: concept confirmation before spending API credits, a quality gate (`$D check`) with regeneration retry, per-agent verification (`ls -lh`) with structured DONE/FAILED reports, fallback to sequential generation on parallel failure, a 10-minute polling timeout with AskUserQuestion fallback, and mandatory feedback-confirmation before saving `approved.json`. This matches the 5-anchor (clear sequence, explicit validation, feedback loops for error recovery). | 5 / 5 |
Progressive Disclosure | There are no bundle files at all (no references/, scripts/, or assets/) — everything lives in one ~710-line monolithic SKILL.md, and the auto-generated marker ("AUTO-GENERATED from SKILL.md.tmpl") shows the shared framework policies are re-inlined per skill rather than split into a common reference one level deep. The design-shotgun section itself is well organized with clear step headings, but content that should be separate is inline, matching the 3-anchor rather than the 4-anchor's "most content is appropriately placed". | 3 / 5 |
Total | 14 / 20 Passed |