spec-review

Review workflow specification artifacts for contract completeness and planning readiness.

2|Updated Mar 27, 2026

Search Tags:#acceptance criteria #spec review #workflow planning #artifact governance #review rounds #product contract

Ready to run

npx skills add https://github.com/bdemarzo/ai-workflows --skill spec-review-bdemarzo

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: spec-review
Source: https://github.com/bdemarzo/ai-workflows/tree/main/skills/spec-review
Command: npx skills add https://github.com/bdemarzo/ai-workflows --skill spec-review-bdemarzo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve?

It helps teams catch spec-contract gaps, unclear acceptance criteria, and artifacts that would derail planning—before work moves forward.

Core Features & Use Cases

Two-subagent substantive review plus skepticism to pressure-test whether the spec is ready to drive plan creation.
Artifact-first governance that preserves the original spec, links prior rounds, and writes a new zero-padded review-round file each pass.
Planning-readiness checks to ensure acceptance criteria are observable, spec boundaries are correct, and repo markdown artifacts are sufficient to continue without chat history.

Quick Start

Use the spec-review skill to review ./docs/workflows/{slug}/spec.md and write the next round to ./docs/workflows/{slug}/reviews/spec/round-XX.md.

Frequently Asked Questions about spec-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I validate acceptance criteria before starting workflow planning?▼

You can validate acceptance criteria before workflow planning by running a spec review that checks if outcomes are observable and bounded, using two substantive reviewer roles plus a skeptic to pressure-test readiness.

What is artifact governance in product spec reviews?▼

Artifact governance in a product spec review preserves the original spec.md file, links prior round feedback, and writes a new zero-padded review-round file for each evaluation pass.

How do I check if a product spec is planning-ready?▼

To check if a product spec is planning-ready, verify that acceptance criteria are observable, spec boundaries are correctly defined, and markdown artifacts contain sufficient detail to continue without chat history.

Can I use a spec review for refactoring and bug fix workflows?▼

Yes, you can use a spec review for refactoring and bug fix workflows, as the validation process fits any capability enhancement where accepted outcomes must be observable and bounded for plan creation.

Why does spec validation require multiple review rounds?▼

Spec validation requires multiple review rounds to ensure accepted outcomes from prior feedback are explicitly incorporated into the latest spec.md, preventing gaps from derailing downstream plan creation.