spec-validate

Spec Validate Skill

Validate requirements through structured clarification. Produces validation data for spec-create.

Reference: See reference/issue-types.md for type definitions, reference/question-taxonomy.md for question templates, and reference/sdd-gates.md for pre-implementation gate definitions.

---

When to Use

Use for:

• New features before implementation
• Unclear requirements needing refinement
• Complex changes needing design exploration
• When multiple approaches seem viable

Don't use for:

• Simple bug fixes
• Well-specified changes
• Clear mechanical tasks (use Claude's native planning)

---

Workflow

Step 0: Check Native Plan Context

Before starting validation, check if the user has existing context from Claude's native /plan:

1. Check for context: Ask if /plan was used or if there's existing plan context
2. If present: Extract key elements:
   • Goal/objective → Seeds Scope taxonomy area
   • Approach/strategy → Seeds Integration/Architecture areas
   • Open questions → Become priority clarification targets
3. If absent: Proceed directly to Step 1

This step bridges native Claude planning with structured validation.

Step 0.5: Constitution Check (Initiatives Only)

For Initiative-type work, verify alignment with constitution before proceeding:

1. Read .claude/constitution.md
2. Check if proposed work aligns with core principles
3. If conflict detected:
   • Flag the conflict
   • Ask user to resolve or justify exception
   • Document exception in validation data

Skip for: Features, Tasks (constitution checked during task-dispatch for Initiatives)

Step 1: Issue Type Selection

FIRST QUESTION (Always) - Use AskUserQuestion:

Header: Work type
Question: What type of work is this?
multiSelect: false
Options:
- Initiative: Strategic coordination (months) - Multiple features toward business goal
- Feature: User-facing capability (weeks) - Deliverable value, multiple tasks
- Task: Implementation item (days) - Single concrete deliverable
- Exploratory: Not sure yet - Gather context first, then classify

This selection determines:

• Question limit: Tasks get 3, Features/Initiatives get 5
• Taxonomy areas: Tasks get minimal (3), Features/Initiatives get full (7)

If Exploratory: Gather context, ask 3 questions to understand scope, present classification recommendation, restart with correct type.

Step 2: Gather Context

1. Examine relevant files, docs, recent commits
2. Understand existing patterns and constraints
3. Initialize taxonomy tracking based on issue type

Taxonomy by type:

Type	Areas to Cover
Initiative	Scope, Behavior, Data Model, Constraints, Edge Cases, Integration, Terminology
Feature	Scope, Behavior, Data Model, Constraints, Edge Cases, Integration, Terminology
Task	Scope, Behavior, Integration

Step 2.5: Ambiguity Scan

Automatically scan gathered context for specification gaps across taxonomy areas.

Process:

1. For each taxonomy area (based on issue type), evaluate:

   • clear: Fully specified, no questions needed
   • partial: Some information present, gaps remain
   • missing: Not addressed at all

2. Populate ambiguity_scan section in validation data:

   ambiguity_scan:
     scope:
       status: clear | partial | missing
       gaps: ["gap description if partial/missing"]
     behavior:
       status: clear | partial | missing
       gaps: []
     # ... remaining areas
   

3. Route based on scan results:

   • No gaps (all clear): Proceed silently to Step 4 (skip validation loop)
   • Gaps found: Areas with partial or missing status become priority candidates for clarification questions in Step 3

Evaluation criteria per area:

Area	Clear	Partial	Missing
Scope	Goals, boundaries, success criteria defined	Some elements unclear	No scope information
Behavior	User flows, system responses specified	Some paths undefined	No behavior described
Data Model	Entities, relationships, formats clear	Schema gaps exist	No data model
Constraints	Performance, security, compatibility stated	Some constraints unclear	No constraints
Edge Cases	Error handling, limits documented	Some cases unaddressed	No edge cases
Integration	Dependencies, APIs, interfaces identified	Some touchpoints unclear	No integration info
Terminology	Domain terms defined consistently	Some ambiguous terms	No definitions

Step 3: Validation Loop

Ask clarifying questions in taxonomy-based batches, with re-evaluation between rounds.

Process:

1. Identify uncovered taxonomy areas
2. Prioritize areas by (Impact × Uncertainty)
3. Group questions by taxonomy area into batches
4. Use AskUserQuestion with multiple questions from the same area
5. Receive answers
6. Re-evaluate remaining questions for relevance (skip questions invalidated by answers)
7. Update taxonomy coverage
8. Repeat with next taxonomy area until limit reached or all Primary areas covered

Batch format:

AskUserQuestion with questions array (1-4 questions per batch):

Question 1:
  Header: [Area, max 12 chars]
  Question: [Clear question ending with ?]
  multiSelect: false
  Options: [2-4 options with implications]

Question 2:
  Header: [Same area]
  Question: [Related question]
  ...

Single question format (when only one question in area):

Header: [Area, max 12 chars]
Question: [Clear question ending with ?]
multiSelect: false
Options:
- Option A: [choice] - [implication]
- Option B: [choice] - [implication]
- Option C: [choice] - [implication]
- None: [default/skip]

Batching rules:

• One batch per taxonomy area (questions grouped by area)
• Multiple trigger fields within a batch combine with OR (any match)

Batch counts:

• Tasks: up to 3 batches (Scope, Behavior, Integration)
• Features/Initiatives: up to 7 batches (all taxonomy areas)
• Plus: additional clarification batches if "Other" answers need follow-up

Batch size limits:

• Tasks: up to 3 questions per batch
• Features/Initiatives: up to 4 questions per batch (AskUserQuestion max)

Re-evaluation between batches:

• After receiving answers, check if pending questions are still relevant
• Skip questions invalidated by previous answers
• If user provides ambiguous "Other" answer spanning areas, add follow-up to next batch

Step 3.5: Initiative-Specific Validation (Initiatives Only)

For Initiatives, ask about user story prioritization and implementation strategy:

Header: User Stories
Question: How should user stories be prioritized?
multiSelect: false
Options:
- MVP First (Recommended): P1 stories deliver standalone value, P2/P3 are incremental
- Parallel Tracks: Stories can be developed independently by different teams
- Sequential: Stories have strict dependencies, must complete in order

Header: Strategy
Question: What implementation approach fits best?
multiSelect: false
Options:
- MVP First (Recommended): Ship P1, iterate on P2/P3 based on feedback
- Incremental: Each phase adds value, all planned upfront
- Parallel Team: Multiple workstreams, integration points defined

Track selections in validation data for spec-create (populates Implementation Strategy section).

Step 3.6: SDD Section Opt-ins (Features Only)

For Features, offer opt-in for detailed SDD sections:

Header: SDD sections
Question: Which detailed sections do you want in the spec?
multiSelect: true
Options:
- Tech Decisions: Document technology choices and rationale
- API Contract: Define API endpoints and schemas
- Data Model: Document entities and relationships
- None: Keep spec lightweight

Track selections in validation data for spec-create.

Step 4: Propose Approaches

Use AskUserQuestion to present options:

Header: Approach
Question: Which approach should we take?
multiSelect: false
Options:
- Approach A: [brief] - Trade-off: [X]
- Approach B: [brief] - Trade-off: [Y] (Recommended)
- Approach C: [brief] - Trade-off: [Z]

Lead with your recommendation. Apply YAGNI ruthlessly.

Step 5: Generate Validation Data

Compile validation data for spec-create:

• Issue type: Selected in Step 1
• Ambiguity scan: Status per area (clear / partial / missing) with gap descriptions
• Questions used: N / limit
• Taxonomy coverage: Status per area (Covered / Gap / N/A)
• Clarification log: Question → Answer → Integration point
• Approach selected: From Step 4
• SDD opt-ins: Which sections selected (Features only)
• Gates status: For Initiatives: run gate checks; for Features/Tasks: mark n/a
• Markers: Any unresolved items identified during validation

This data passes to spec-create for validation.yaml.

---

Key Principles

Principle	Why
Issue type first	Branches workflow, sets question limit
Ambiguity scan	Identifies gaps early, skips validation if all clear
MultiSelect always	Structured options, faster iteration
Question limits	Forces prioritization
Taxonomy tracking	Ensures coverage of important areas
YAGNI ruthlessly	Remove unnecessary features

---

Output

This skill produces validation data, not documents. The data flows to spec-create which generates:

• spec.md, context.md, tasks.md, dependencies.yaml, validation.yaml

---

Integration

Invoked by: /spec.create command (default behavior)

Standalone use: Can be invoked directly via spec-validate skill for validation without document creation.