/specs.spec-check

description: "Resolves [NEEDS CLARIFICATION] markers generated during brainstorming and performs a structured quality scan to identify underspecified areas. Integrates responses directly into the specification. Use after specs.brainstorm before specs.spec-to-tasks."
argument-hint: "[ --spec=\"docs/specs/XXX-feature\" ]"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, TodoWrite
model: inherit

Spec Check — Clarification & Quality Assessment

Resolves `[NEEDS CLARIFICATION]` markers from brainstorming and performs a structured ambiguity scan to harden the specification before task generation.

Overview

This command has two functions:

| Function | When it runs | Description | |----------|-------------|-------------| | **Resolve [NEEDS CLARIFICATION]** | Always first | Process markers generated by `specs.brainstorm` — up to 3 questions with priority | | **Structured Ambiguity Scan** | If space remains (max 5 questions total) | Scan the spec for underspecified areas using a taxonomy of categories |

When [NEEDS CLARIFICATION] markers exist

The markers are the **primary source** of clarification questions. Each marker becomes a pre-built question. The scan runs only if fewer than 5 questions are needed to resolve all markers.

When no [NEEDS CLARIFICATION] markers exist

The command falls back to a **full structured scan** across all quality categories, identical to the v3.0 behavior.

Workflow Position

brainstorm → spec-check (this) → spec-to-tasks → task-implementation → task-review → sync
               ↑
        Resolve [NEEDS CLARIFICATION]
        Generate da specs.brainstorm

Dimensions of Quality

The command evaluates four main dimensions:

1. **Completeness and Clarity**

• Vague expressions ("robust", "intuitive", "fast")
• Terms not defined in glossary
• Internal contradictions
• Missing or incomplete sections

2. **Requirements Traceability**

• User request → specification alignment
• Requirements → tasks coverage (if tasks exist)
• Clear origin for each requirement

3. **Acceptance Criteria**

• Presence of testable criteria
• Measurability of criteria
• Coverage of key functionalities

4. **Edge Cases Coverage**

• Edge cases identified
• Error handling documented
• Explicit constraints and limitations

5. **Architecture Alignment** (if `docs/specs/architecture.md` exists)

• Specification requirements consistent with defined technology stack
• No implicit technical assumptions that contradict the architecture
• Integration points compatible with infrastructure choices
• Data requirements aligned with data architecture

6. **Ontology Consistency** (if `docs/specs/ontology.md` exists)

• Domain terms in the specification match ontology definitions
• No ambiguous synonyms (terms used interchangeably without definition)
• Bounded contexts are respected (same term not used with different meanings)
• New domain concepts flagged for ontology addition

Usage

# Basic usage - review a spec folder
/developer-kit-specs:specs.spec-check docs/specs/001-hotel-search-aggregation/

# Review a specific spec file
/developer-kit-specs:specs.spec-check docs/specs/001-hotel-search-aggregation/2026-03-07--hotel-search.md

# Review from current directory (auto-detect)
/developer-kit-specs:specs.spec-check

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `spec-path` | No | Path to spec folder or file (default: auto-detect from CWD) |

Current Context

If `--spec` is omitted, the spec folder is auto-detected from the current git branch:

branch=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/current_branch.py")
spec_folder=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/find_spec_from_branch.py")

If no matching spec folder is found for the current branch, stop and inform the user.

Core Principles

• **Maximum 3 markers to resolve**: Focus on the most impactful clarifications first
• **Maximum 5 questions total**: Focus on the most impactful ambiguities (markers + scan combined)
• **One question at a time**: Interactive presentation with recommendation
• **Immediate integration**: Responses are integrated into the specification progressively
• **Recommendation based on best practices**: For each question, suggests the best option
• **Non-destructive**: Preserves existing content, only adds clarifications
• **Final report**: Summary of resolved, deferred, and outstanding areas
• **Deferred markers handling**: Markers exceeding limit are queued for next session

---

Integration with specs.brainstorm

Marker Generation (in specs.brainstorm)

During brainstorming, the agent marks unclear aspects with:

[NEEDS CLARIFICATION: specific question text]

Rules for marker generation (max 3 total):

• Used only when: scope impact, multiple interpretations, no reasonable default
• Prioritized by: scope > security/privacy > user experience > technical details
• Not used for: reasonable defaults (data retention, auth method, error handling patterns)

Marker Resolution (in this command)

This command: 1. Extracts ALL `[NEEDS CLARIFICATION: ...]` markers from the spec 2. Converts each marker into a structured question (multi-choice or short-answer) 3. Presents them as the FIRST questions (before scan-generated questions) 4. Removes the marker from the spec after resolution 5. Integrates the answer into the appropriate section

---

Phase 1: Discovery

**Goal**: Identify the specification to review and gather context

**Actions**:

1. Create todo list with all phases 2. Parse $ARGUMENTS to extract the specification path 3. Determine the specification folder:

• If a file is provided: use the parent directory
• If a folder is provided: use it directly
• If no argument: auto-detect from current working directory

4. Verify the folder exists 5. Identify relevant files:

• `YYYY-MM-DD--feature-name.md` -