Content
70%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-sequenced, checkpoint-rich process skill with strong conciseness and workflow clarity, whose document template, company config, and several companion skills are referenced but absent from the bundle. Actionability suffers because Phase 3 depends entirely on a template file that is not shipped, and external tool invocations have no inline fallback.
Suggestions
Bundle `spike-template.md` (and `company-config.yaml`) in the skill directory or inline the template's section structure in SKILL.md — Phase 3.2's 'Every section must be populated' is unactionable without the referenced template.
Provide inline fallback instructions for external dependencies (grill-me, devflow:codebase-walkthrough, devflow:retain-learning, Nimbalist task-file format) so the phases remain executable when those skills/tools are unavailable.
Trim the redundant persona framing and the duplicated 'Every section must be populated' line in section 3.2 to tighten token usage.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative — phases, tables, and bullet directives with almost no explanation of concepts Claude already knows (e.g., the DB section jumps straight to "CREATE INDEX CONCURRENTLY, pg_repack, gh-ost, start batch=1000"). Minor trimmable redundancy exists: the persona paragraph ("You are a senior staff engineer... You've seen spikes that changed architectural direction") and the duplicated instruction "Every section must be populated" in 3.2. | 4 / 5 |
Actionability | Concrete guidance is substantial (parallel subagent assignments, category classification rules, explicit save paths, a 10-row quality gates table, specific DB techniques), but key details are missing: "Follow the template in `spike-template.md`" and "Read `company-config.yaml` from the skill directory" point to files that do not exist in the bundle, and external skills ("Invoke grill-me", "devflow:codebase-walkthrough", "devflow:retain-learning", Nimbalist task files) are invoked with no bundled definitions or inline fallbacks, so the document-generation phase is not executable as shipped. | 3 / 5 |
Workflow Clarity | The four phases are explicitly sequenced (reinforced by a Mermaid flowchart and "Every phase is mandatory. Do not skip phases."), with validation checkpoints throughout: a scope check after Phase 1 with concrete thresholds ("30+ spike goals, 10+ external dependencies"), user decision points ("Decide now, discuss with team, or defer?"), a 10-gate quality checklist in 3.4, and a self-review feedback loop in 4.1 ("Placeholder scan, internal consistency, scope check, ambiguity check. Fix inline.") plus grill-me adversarial review in 4.2. Defaults and safety rails are explicit ("Default: keep local. Never auto-publish."). | 5 / 5 |
Progressive Disclosure | Section structure per phase is good and references are clearly signaled one level deep ("REQUIRED REFERENCE: Follow the template in `spike-template.md` (same directory as this skill)"), but no bundle directory exists and neither referenced file (spike-template.md, company-config.yaml) is present, so the navigation chain is broken and the skill functions as a monolith with dangling references. This is between anchor 3 (references present but the organization is incomplete) and anchor 2, landing at 3 because the in-body structure itself is well organized. | 3 / 5 |
Total | 15 / 20 Passed |