spec-planning

Reads a PRD (`prds/<feature>/prd.md`) plus its executable `run-prd-test.sh` (and any helper artifacts under `prds/<feature>/`), grounds them in codebase research, and produces `specs/<feature>/mainspec.md` plus dependency-ordered slices. Encodes the runner as a slice success criterion so implementation completion implies `./prds/<feature>/run-prd-test.sh` exits 0. Touches `specs/<feature>/.planning-done` as its final committed action. Agent-first — no human-in-the-loop.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/sdd/spec-planning/SKILL.md

Quality

Content

73%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-engineered operational core: the invocation contract, completion protocol, and recovery branches give an implementing agent everything needed to execute deterministically, with strong validation checkpoints and real reference files. The main costs are token bloat from philosophy prose and long generic examples inlined in SKILL.md, plus a missing full mainspec template.

Suggestions

Move the six Context Engineering subsections (BEFORE/AFTER, type contracts, DO/DON'T, Mermaid flows, forward-looking requirements, directory structures) into a `references/context-engineering.md` and keep a one-line summary per practice in SKILL.md — this is the biggest token and organization win.

Trim the 'Spec-Driven Development & Your Role' narrative paragraph to two or three imperatives; the Guidelines section already conveys the same rules, and state the 'MUST Read references/experts.md and references/signals.md' instruction once instead of three times.

Add a full mainspec template (sections it must contain, ending with the Slice Dependency Map) mirroring the slice template, so the primary output artifact is as unambiguous as the slices.

Dimension	Reasoning	Score
Conciseness	The operational core (Invocation Contract, Guidelines, Output Structure) is efficient, but the 'Spec-Driven Development & Your Role' philosophy paragraph, repeated 'MUST Read the catalog' instructions, and ~180 lines of generic TypeScript/email examples in Context Engineering are explanation and padding that could be tightened or cut.	3 / 5
Actionability	Concrete, executable guidance throughout: exact invocation command, precise input/output paths, a numbered completion protocol, idempotency and crash-recovery branches, slice naming conventions, and copy-paste markdown templates for the dependency map and Signal sections. Falls short of 5 because the mainspec — the primary output artifact — has no template beyond the Slice Dependency Map ending.	4 / 5
Workflow Clarity	The multi-step process is clearly sequenced with explicit validation (the sentinel must be the final commit only after all artifacts are in place), feedback loops for error recovery (crash-recovery branch: 'verify the existing artifacts are complete and self-consistent, fix any gaps, then write the sentinel'), and a re-fire loop for ambiguous PRDs.	5 / 5
Progressive Disclosure	Both referenced files (`references/experts.md`, `references/signals.md`) exist, are one level deep, and are clearly signaled as 'MUST Read' at the start of planning. Falls short of 5 because the six-subsection Context Engineering example block (~180 lines of inline examples) is content that clearly belongs in a separate reference file.	4 / 5
	Total	16 / 20 Passed

Description

67%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A highly specific, well-bounded description that states concrete inputs, outputs, and behaviors with exact paths. Its main weaknesses are the absence of any explicit 'use when' trigger guidance and reliance on internal jargon over natural trigger terms, which limit discoverability and completeness.

Suggestions

Add an explicit trigger clause, e.g. 'Use when a PRD exists at `prds/<feature>/prd.md` and needs to be turned into a spec plan' — the missing 'when' currently caps completeness at 3.

Include natural synonyms alongside the jargon, e.g. 'PRD (product requirements document)' and 'specification slices', so the description matches phrases a user or dispatcher would naturally say.

Spell out less common terms like 'mainspec' (e.g. 'main specification (mainspec.md)') to improve natural-language matching without losing precision.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions with exact paths — 'Reads a PRD (`prds/<feature>/prd.md`) plus its executable `run-prd-test.sh`', 'produces `specs/<feature>/mainspec.md` plus dependency-ordered slices', 'Encodes the runner as a slice success criterion', 'Touches `specs/<feature>/.planning-done`' — comprehensive coverage of the skill's behavior in third-person voice.	5 / 5
Completeness	The 'what' is clear and detailed, but there is no 'Use when...' clause or equivalent explicit trigger guidance — 'Agent-first — no human-in-the-loop' only weakly implies when the skill applies, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	Domain terms like PRD, spec, slices, and planning are present and relevant, but common natural variations and synonyms ('product requirements document', 'specification', 'break down', 'feature plan') are missing, and the vocabulary leans toward internal jargon (mainspec, sentinel, dispatcher) rather than phrases a user would naturally say.	3 / 5
Distinctiveness Conflict Risk	The description carves out a clear niche (PRD-to-spec planning) with distinct artifacts — the `run-prd-test.sh` success-criterion encoding and the `.planning-done` sentinel — making it highly distinguishable from generic planning or documentation skills.	5 / 5
	Total	16 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: tdg-ninja/context-specs-factory-ai
Path: skills/sdd/spec-planning/SKILL.md
Commit: 3a7a725

Reviewed: 2 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.