---
name: speckit-spec-validate-validate-09c213e100b4
description: 'Spec-kit workflow command: speckit-spec-validate-validate'
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: github-spec-kit
  source: spec-validate:commands/validate.md
---

# Validate Spec Comprehension

## Command: `speckit.spec-validate.validate`

Validate the current feature's `spec.md` through staged-reveal multiple-choice quizzes.

## Prerequisites

- A generated `spec.md` exists for the current feature
- Shell scripts are available: `compute-hash.sh`, `read-approval-state.sh`, `write-approval-state.sh`

## Execution Flow

### Step 1: Load and Hash

1. Determine the current feature directory from `.specify/feature.json`
2. Read `spec.md` from the feature directory
3. Run `compute-hash.sh <path-to-spec.md>` to get the SHA-256 hash
4. Store the hash for later — this binds validation to this specific content version

### Step 2: Classify Items

1. Parse spec.md into sections (User Scenarios, Requirements, Success Criteria, Edge Cases, etc.)
2. Load `always_critical_sections` from the extension config (`spec-validate-config.yml`):
   - Default critical sections: "Acceptance Criteria", "Edge Cases", "Error Handling", "Security Considerations"
3. For each item in the spec:
   - If item is in a critical section → classify as **critical** (multiple-choice confirmation)
   - If item is straightforward/obvious → classify as **simple** (acknowledge-only)
4. Count critical items. If **0 critical items**: auto-pass — skip to Step 5 with `spec_self_validation: "passed"` and `spec_critical_count: 0`

### Step 3: Staged Reveal

Present sections **one at a time**, blocking progression until the current section is complete.

**For simple items:**
- Display the item
- Ask: "Does this look correct?" (acknowledge-only)
- Move to next item

**For critical items:**
1. Load `.specify/templates/distractor-patterns.yml` to determine the distractor pattern category:
   - Behavioral requirement → behavioral pattern
   - Error-handling requirement → error_handling pattern
   - Data/entity requirement → data_constraint pattern
   - Edge case → edge_case pattern
   - Security requirement → security pattern
2. **Deterministic-first**: Generate 2 distractors using the matched pattern template
   - `decoy_1`: Apply the weaker/generic fallback pattern
   - `decoy_2`: Apply the conflicting/opposite behavior pattern
3. **AI fallback**: If deterministic generation cannot produce distinct, plausible distractors for this specific item, use AI to generate contextually appropriate alternatives
4. Present 3 options in **shuffled order** (1 correct + 2 decoys)
5. Wait for user selection
6. **On correct**: Mark item as `confirmed`
7. **On wrong**: Highlight the correct answer, mark item as `missed`, **move to next item (no retries)**

**Agent adaptivity:**
- For agents supporting `vscode/askQuestions`: use that tool for clean multiple-choice UI
- For CLI agents: present options as numbered list in conversational flow
- Fall back gracefully between modes

**Do NOT reveal the next section until the current section is complete.**

### Step 4: Record Results

After all sections are validated:

1. **Git-tracked state** — Run `write-approval-state.sh <feature> <json>` with:
   ```json
   {
     "feature": "<feature-id>",
     "spec_hash": "<hash from Step 1>",
     "spec_self_validation": "passed",
     "spec_validated_at": "<ISO8601 timestamp>",
     "spec_critical_count": <number>,
     "spec_missed_items": ["<item-ids that were missed>"],
     "review_status": "<computed in Step 5>",
     "approval_status": "<computed in Step 5>"
   }
   ```
   Preserve existing `tasks_hash`, `tasks_self_validation`, and other fields.

2. **Local private state** — Write to `.specify/extensions/spec-validate/local/<feature>.private.json`:
   ```json
   {
     "feature": "<feature-id>",
     "validated_by": "<current user or session id>",
     "agent": {"name": "<agent-name>", "version": "<agent-version>"},
     "attempts": [
       {"artifact": "spec.md", "item_id": "<id>", "selected_option": "<text>", "correct": true/false}
     ],
     "analytics": {
       "first_attempt_accuracy": <float 0-1>,
       "total_items": <int>,
       "critical_items": <int>,
       "items_missed": ["<item-ids>"]
     }
   }
   ```
   Create the `local/` directory if it doesn't exist. This directory MUST be gitignored.

### Step 5: Determine Review Requirement

Evaluate review policy from config:

1. **Solo developer** (team size = 1 or no reviewers available): Skip review entirely. Set `review_status: "not-required"`, `approval_status: "allowed"`
2. **Any missed items** AND `review.require_on_any_miss: true`: Set `review_status: "pending"`, `approval_status: "blocked"`, record `review_requested_at`
3. **Medium/high complexity** (critical items >= `complexity.high_min_items` or between low and high) AND `review.require_on_medium_or_high_complexity: true`: Set `review_status: "pending"`
4. **Perfect score + low complexity** (critical items <= `complexity.low_max_items`): Set `review_status: "not-required"`, `approval_status: "allowed"`
5. **Perfect score + medium/high complexity**: Apply complexity-based review rule from config

### Step 6: Report

Display validation summary:
- Total items validated
- Critical items count
- First-attempt accuracy percentage
- Items missed (list IDs)
- Review status (required / not required)
- Next steps (run `/speckit.spec-validate.review` if review pending, or proceed to planning/tasks)


---
Source attribution: eitatech
Original project: https://github.com/eitatech/gatomia-vscode/blob/081a9aadc7c7680b5b2b4f728042dc2a9f7e8dcc/.agents/skills/speckit-spec-validate-validate/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 atman-33

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: eitatech
Original project: https://github.com/eitatech/gatomia-vscode/blob/081a9aadc7c7680b5b2b4f728042dc2a9f7e8dcc/.agents/skills/speckit-spec-validate-validate/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Product Manager, QA / Test Engineer, Technical Product Manager
Specialties: Testing
Tools: Spec Kit
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 376db4bf479092c362447f85b9658432ede712a30d9d73e26c8ed1b2157ccf2b