dasha-ws/ai-dev-framework/review-spec

review-spec

Purpose

/review-spec is the mandatory independent quality gate for specifications. Nothing moves on to the next significant stage until the spec feeding that stage has passed here.

It reviews exactly one spec per run:

• Product Specification: .claude/product/product-spec.md
• Feature Specification: .claude/work/<feature-name>/feature-spec.md
• Tech Specification: .claude/work/<feature-name>/tech-spec.md

It identifies the target and its type, checks the prerequisites, hands the spec to the matching independent reviewer-agent, validates the reviewer's output and integrity, returns the outcome and stops. It never creates, rewrites, fixes or approves a spec itself. The reviewer is independent of whoever wrote the spec: "I wrote it, I fixed it, I gave myself a PASS" is the loop this gate exists to break.

The outcome is PASS, FAIL, or no verdict when the review could not validly take place (step 7 defines all three). A PASS belongs only to the version that was reviewed. What follows is governed by "Next skills".

When to use

• After /product-spec, /new-feature-spec or /tech-spec created or substantially updated a spec.
• After the findings of a previous FAIL were fixed, before moving on.
• When a spec changed after its PASS, or when it cannot be established whether the current version ever passed.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop without a verdict, say what is missing and suggest /init-project (step 2).
• The user wants a spec written, changed or fixed: /product-spec, /new-feature-spec or /tech-spec. This skill only judges.
• The user wants several specs reviewed at once. One spec per run: ask which goes first.
• The target lives in .claude/work/completed/. A finished work item is not an active gate, unless the user explicitly asks to review it.
• The user wants a finished implementation checked against the product goal (/review-spec never calls product-reviewer), code reviewed (/review-code) or a finished feature tested (/test-feature).

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The target spec. Named by the user, or unambiguously determined from the current work item or context. Never guessed.
• The framework structure in the target project, created by /init-project: root CLAUDE.md, .claude/skills/project-context/SKILL.md, .claude/skills/project-context/context/product.md, .claude/product/product-spec.md and .claude/work/. All are required.
• The installed specification template for the target's type. It lives under %USERPROFILE%\.claude\ai-dev-framework\templates\: product-spec.md for a Product Spec, work\feature-spec.md for a Feature Spec, work\tech-spec.md for a Tech Spec. Do not look for it by other means.
• The reviewer-agent for the target's type, as provided by the current installation.

The mapping is fixed:

One reviewer-agent per spec. Several on the same spec only under a separate framework rule.

Files to read

Read before calling the reviewer. All reads are read-only. The reviewer gets the same context, not more. The one exception is an explicitly defined post-PASS routing-only read, below: it happens only after a valid PASS and is never handed to the reviewer. Follow the router and do not load everything.

Always: the root CLAUDE.md, .claude/skills/project-context/SKILL.md (the router), the target spec and the installed template for its type. Then, per type:

• Product Spec: product.md. Other product-level material (README, product documentation, the observable behaviour of an existing product) only where the review really needs it, in the smallest amount. No technical audit.
• Feature Spec: .claude/product/product-spec.md and product.md. Relevant documentation, current observable behaviour and related current or completed specs only when needed. A Feature Spec review is not a code review. After a PASS, only to route (see "Next skills"), the current architecture.md, read-only. It is not handed to the reviewer.
• Tech Spec: the applicable upstream requirements spec (step 3); the Product Spec and product.md as far as the requirements need them; the CURRENT architecture.md, always; the relevant parts of development.md and infrastructure.md; ux-guide.md only if the UI or UX of the work item is relevant. Existing code, configuration, package, build and test files and API or schema definitions only as far as needed to judge whether the Tech Spec fits the existing project. This is not a code audit.

Never read real .env files, credentials or secrets.

Execution steps

1. Identify the target and its type

The target is named by the user or unambiguously determined from the current work item or context. Do not guess. If several specs are possible: show the candidates in a few lines, ask which one to review and do not start until the user answers. Never review several in one go. A target in .claude/work/completed/ is not used as an active gate without the user's explicit request.

Determine the type from purpose and location, as in the mapping table. If the location is unexpected or the type ambiguous, ask the user or stop and explain. Do not invent a new specification type.

2. Check that the review can take place

Process problem. If a prerequisite fails, the template or the reviewer is unavailable, or the reviewer's output cannot be validly accepted (step 6), the review did not validly take place. There is no verdict: no PASS and no FAIL. A problem found before the reviewer is called means the reviewer is not called. Stop, report the blocker and the required next action, and do not count the review as done. A broken process is never a content FAIL. The one exception is a reviewer mutation together with an independently established FAIL (step 6). Everywhere in this skill, "no verdict" means this rule.

Verify that the working directory is a target project, not the framework repo, and that the base framework structure from "Inputs" exists. If any of it is missing: no verdict, say what is missing and suggest /init-project. Do not create the structure yourself and do not rebuild it from memory. Then verify that:

• the target spec exists, is not empty and is not a not-started or template-only stub, and its type is supported. If not, there is nothing to review: suggest the matching skill (/product-spec, /new-feature-spec or /tech-spec) and do not launch it;
• the installed template for the type is available and not empty, and the right reviewer-agent is available. If not, say that the framework installation needs fixing and what exactly is missing. Do not recreate the template from memory, do not invent your own review structure, do not imitate the reviewer or substitute another agent, do not create an agent and do not invent a verdict.

For a Feature Spec, the product context must be clear enough to review it: a substantive Product Spec or, if it is a not-started stub, existing project context that already defines the product clearly enough (the same rule as in /new-feature-spec). Do not fill the gaps with assumptions. If it is not clear enough: no verdict, suggest /product-spec. A FAIL is legitimate only when the review did take place and the reviewer concluded that the Feature Spec itself is insufficient.

3. Check the Tech Spec prerequisites (Tech Spec only)

None of this is added to a Product Spec or Feature Spec review. Everything here is checked before the tech-spec-reviewer is called. /review-spec only establishes what was already completed. It designs no architecture and takes no architecture decision.

Reliably established. A fact or PASS named in this step, except the feature-implementation workflow (which follows from the work-item folder, see below), counts as reliably established in exactly three cases:

1. the current conversation or workflow contains it for this very version, and there has been no substantive change since;
2. the user explicitly confirms it for this very version, and that there has been no substantive change since;
3. the workflow ledger .claude/work/status.md has a row for it that powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check reports FRESH. The script decides freshness, not your own judgment of whether a change was substantive. A STALE or missing row is not established.

In every other case it is not established. Never infer it from a file existing, from a non-empty or hand-filled file, from the content of the Tech Spec, from git history, commits, timestamps, naming or comments, or from your own fresh analysis, and do not guess. If the conversation or a FRESH ledger row already establishes it, do not ask for a ritual confirmation. The ledger is the only recorded state: no other status file, registry, version tracking, approval field in a spec or report file.

Workflow. Establish which workflow the work item belongs to. Do not guess.

• Feature implementation on an existing product. The upstream requirements spec is .claude/work/<feature-name>/feature-spec.md. If the matching feature-spec.md exists in the same work-item folder as the target tech-spec.md, that is a sufficient structural basis, normally with no confirmation needed, and the absence of a confirmation is not a conflict. A missing Feature Spec is not a fallback to the Product Spec. If substantial existing-product work has no Feature Spec: no verdict, route to /new-feature-spec → /review-spec → /tech-spec.
• Initial product implementation. The upstream is .claude/product/product-spec.md, and a separate Feature Spec is not required. This is the only case where the Product Spec is the direct upstream of a Tech Spec. Without a matching Feature Spec it is reliably established only if the conversation or workflow explicitly shows that this Tech Spec was created as an initial product implementation, or the user explicitly confirms it. It is not evidenced by a missing Feature Spec, the name of the work item or its folder, the content of the Product Spec, or the Tech Spec merely existing. If it cannot be established, do not fall back to the Product Spec and do not guess. Ask the user if a short clarification is enough, otherwise stop with the prerequisite ambiguity and no verdict.
• Workflow conflict. The matching feature-spec.md exists, but the conversation or an explicit user statement directly says that this same work item is the initial product implementation. Neither side wins automatically: the structure does not override the statement, and the statement does not override the structure. Do not call the reviewer, give no verdict, show the contradiction briefly and ask which workflow is right, then continue with the matching upstream. A clarification that it is an initial product implementation counts as the explicit confirmation required above. Only an explicit statement to the opposite makes a conflict.