Summary
spec-verify is a Claude Code skill that takes the Given/When/Then acceptance criteria generated by spec-writer and turns them into tests that are checked. It exists to force the gap between “looks done” and “is done” to be crossed deliberately, with the reason written down.
The tool’s origin is a hallucination fix. A clean run showed zero out of five fabricated responses, and the result was signed off as “HUMAN-VERIFIED.” A harder rerun produced 66.7% instead. The lesson: one clean run and “verified” are not the same thing — and the author nearly let that distinction slide in a tool built specifically to enforce it.
Key Points
- Converts spec-writer’s Given/When/Then acceptance criteria into executable tests.
- Reports should be scanned like spec-writer’s Assumptions summary: look first for anything that is not VERIFIED.
- VACUOUS and BROKEN-TEST findings mean go fix the test; no version of that finding is fine to ship.
- UNVALIDATABLE findings require an explicit decision: either a human checks the behavior by hand and says so on the record, or the behavior is moved somewhere testable.
- In the trilogy described in the notes, spec-writer catches the feature you built for the wrong reason; spec-verify catches the test that would have told you that, and didn’t.
- Between the two, an assumption gets flagged and corrected before the code ships, and a test now exists that fails if the correction is undone six months later by someone who never read the original spec.
- The repository is at github.com/dannwaneri/spec-verify.
Concepts
- spec-writer: The companion skill that produces acceptance criteria. Its Assumptions summary format is the model for reading spec-verify reports.
- Verification statuses: VERIFIED, VACUOUS, BROKEN-TEST, UNVALIDATABLE. Anything that is not VERIFIED needs action.
- Entity-grounding fix: An example of behavior that could not be validated as written; the solution was to move it into a testable location.
- Mutation testing: The recommended way to discover vacuous tests before shipping them.
- Trilogy: The combined workflow in which spec-writer, spec-verify, and human judgment each catch a different failure mode.