Content
73%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 an operationally precise playbook: four clearly discriminated intents, each with concrete commands, hard propose-then-confirm checkpoints, and explicit decline/cleanup handling. Its weaknesses are trimmable verbosity (pattern citation, repeated lifecycle-record explanation) and a couple of commands referenced by name only.
Suggestions
Compress the interview-pattern section to its rule (adaptive questions toward a stated goal, stop when answers stop changing the document) and drop the citation and pattern exposition, saving the load-bearing stopping condition.
State the two-classes distinction once and have the revise branch reference it in one line instead of re-explaining byte-for-byte storage and lifecycle records.
Show the full `spektacular design ref remove` invocation (its --data shape) as is done for ref add and ref list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is instruction-dense with no explaining of concepts Claude already knows, but it could be tightened: the Flipped Interaction citation and pattern exposition ("rather than asking the user to author the document from a blank prompt, you drive the conversation...") spends lines justifying a style one sentence could command, and the two-classes distinction (lifecycle record vs. stored-as-supplied) is explained at the top and re-explained in the revise branch. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened'; it is not a 2 because the padding is stylistic rather than tutorial-level. | 3 / 5 |
Actionability | Nearly every branch gives copy-paste-ready commands with explicit JSON payloads and flags (e.g. `spektacular design author --data '{"source":"<name>","path":"<path>"}' --from .spektacular/tmp/<slug>.md`, including `--document-status <draft|final|superseded|archived>`). The minor gap keeping it from 5: `spektacular design ref remove` is named with no invocation shown, so it is not fully copy-paste ready across all cases. | 4 / 5 |
Workflow Clarity | Each of the four branches is a numbered, explicitly sequenced procedure with a hard validation checkpoint ("Present the draft to the user as ordinary readable text, in full, and get their explicit agreement before writing anything"), and the Decline handling section supplies a genuine error-recovery feedback loop (loop back and refine, or stop and remove the staged scratch file at `.spektacular/tmp/<slug>.md`), plus trace `--status error` on helper failure. This matches 'clear sequence with explicit validation steps; feedback loops for error recovery'. | 5 / 5 |
Progressive Disclosure | The body is organized into well-labeled sections (version check, tracing, what/when, four intent branches, decline handling) with one topic per section, and it is a single-level skill with no nested references — no bundle files exist and none are referenced. It is not a 5 because at ~165 lines some self-contained material (the interview pattern exposition, the full command/flag reference) would sit better in a reference file, matching 'good structure; most content is appropriately placed; minor organization gaps'. | 4 / 5 |
Total | 16 / 20 Passed |