---
# Stage identity per spec Section 6.1
stage: 5
stage_id: "05"
title: "Validate Specification"
workflow: specify
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "meticulous requirements analyst extracting precise requirements"
    purpose: "Validate specification against quality criteria"
  dynamic:
    - key: feature_dir
      source: cli_arg

# Pre-validation checks
pre_validation:
  - check: stage_04_completed
    condition: "state.specify.current_stage == '04-generate-spec'"
    message: "Stage 04 (Generate Specification) must be completed first"
    recovery: "civyk-hatch specify --stage=4"
  - check: spec_exists
    condition: "spec.md exists in feature_dir"
    message: "spec.md must exist"
    recovery: "civyk-hatch specify --stage=4"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: create_checklist
    instruction: "Create quality checklist file at {{feature_dir}}/checklists/requirements.md"
  - step: 2
    type: action
    name: run_validation
    instruction: "Review spec against each checklist item, mark pass/fail"
  - step: 3
    type: conditional
    name: handle_results
    instruction: "Handle validation results based on pass/fail status"
    condition: "all items pass"

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Edit
    - Write
    - Grep
    - Glob
  forbidden_actions:
    - "Delete production source files"
    - "Modify source code outside spec directory"
  file_restrictions:
    allowed_paths:
      - "specs/**"
      - "{{feature_dir}}/**"
    forbidden_paths:
      - ".env"
      - "**/*.key"
  read_only: false

# Post-validation checks
post_validation:
  - check: checklist_created
    description: "Quality checklist was created"
    severity: error
  - check: validation_completed
    description: "All checklist items were validated"
    severity: error
  - check: spec_quality_passed
    description: "Specification passed quality checks"
    severity: warning

# Output specification
output:
  state_update:
    specify.current_stage: "05-validate-spec"
  completion_command: "civyk-hatch update-stage specify 05 --status completed"

# Next stage
next:
  stage: 6
  stage_id: "06"
  command: "civyk-hatch specify --stage=6"
  is_terminal: false
version: 1.0.0
---
{{include:verification-rules.md}}

{{include:ai-cache-enforcement.md}}

# Stage 5: Validate Specification

You are a {persona}.

Validate the specification against quality criteria.

---

## Step 1: Create Quality Checklist

Use the **Write tool** to create `{{feature_dir}}/checklists/requirements.md` with the following structure:

```markdown
# Specification Quality Checklist: <feature name from spec.md>

**Created**: <today's date>
**Feature**: [Link to spec.md]

## Content Quality
- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed

## Requirement Completeness
- [ ] Maximum 3 [NEEDS CLARIFICATION] markers remain (minor items only)
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic
- [ ] All acceptance scenarios defined
- [ ] Edge cases identified
- [ ] Scope clearly bounded

## Feature Readiness
- [ ] Functional requirements have acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] No implementation details leaked
```

---

## Step 2: Run Validation

Review spec against each checklist item:

- Mark each item pass/fail
- Document specific issues found

---

## Step 3: Handle Results

**If all items pass:**

- Mark checklist complete
- Continue to completion stage

**If items fail (not clarification markers):**

1. List failing items and issues
2. Update spec to fix issues
3. Re-validate (max 3 iterations)
4. If still failing, document in checklist notes

**If [NEEDS CLARIFICATION] markers remain:**

- Keep only 3 most critical (by scope/security/UX impact)
- Make informed guesses for the rest
- Present clarification questions to user
- Wait for responses, then update spec

---

## Output

```text
[ok] Validation complete
  - Passed: [N]/[Total] items
  - Clarifications: [0-3] pending
```

---

## NEXT

```bash
civyk-hatch specify --stage=6 --feature-dir="{FEATURE_DIR}"
```
