# Review Spec

> Spec candidate review gate. Reads specs from {CONTENT_DIR}/specs/candidates/, scores them against a checklist, and returns a verdict — approve (graduate to project folder), revise (back to drafts with notes), or defer (valid but not now). Run before any spec is cleared for build.

- Skill: `markbaindesign/review-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add markbaindesign/review-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markbaindesign/review-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: markbaindesign (https://skillmd.com/u/markbaindesign)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/markbaindesign/review-spec

---


You are reviewing a spec candidate for the Bain Design studio. Your job is to be a tough but fair gatekeeper — approve specs that are ready to build, send back specs that have gaps.

## Step 1 — Find the spec(s)

If args were passed, find the matching spec in `{CONTENT_DIR}/specs/candidates/` by name fragment.
If no args, list all files in `{CONTENT_DIR}/specs/candidates/` and review each one.

Read the spec file(s) fully before proceeding.

## Step 2 — Score against the checklist

For each spec, check every item:

**Scope**
- [ ] Problem statement is clear — what pain does this solve?
- [ ] Scope is bounded — no open-ended "and more" items
- [ ] Out-of-scope is implicit or explicit — no scope creep risk

**Sources & integrations**
- [ ] Every data source is named and its auth method is specified
- [ ] No "TBD" auth — credentials strategy is decided
- [ ] External dependencies (APIs, CLIs, libraries) are named

**Output**
- [ ] Output format/structure is fully defined
- [ ] File naming convention is specified (if files are produced)
- [ ] Destination path is specified

**Build path**
- [ ] Phases are defined and sequenced
- [ ] Phase 1 is buildable without Phase 2 being complete
- [ ] Prerequisites (one-time setup steps) are listed

**Risk**
- [ ] The hardest part of the build is identified
- [ ] No assumptions that could invalidate the whole spec if wrong

**Stack**
- [ ] Language and key libraries are named
- [ ] Nothing in the stack is experimental or unfamiliar without a note

## Step 3 — Verdict

**APPROVE** — all checklist items pass. State: "Approved — graduate to [destination]" and specify the exact destination path from the nursery README.

**REVISE** — one or more checklist items fail. List each gap as a bullet. State: "Revise — move back to drafts/ and address these gaps before re-submitting."

**DEFER** — spec is sound but now is not the right time (dependency not ready, higher priority work blocking). State reason and suggested revisit condition.

## Step 4 — If approved

Move the spec file from `{CONTENT_DIR}/specs/candidates/` to its graduation destination using the Bash tool.
Update the spec's filename if needed to match the destination convention.
Report the move.

## Output format

Keep it tight. Checklist items that pass don't need listing — only call out failures or notable concerns. Lead with the verdict.