---

# Stage identity per spec Section 6.1
stage: 2
stage_id: "02"
title: "Clarify Requirements"
workflow: checklist
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "rigorous QA engineer determining checklist focus"
    purpose: "Determine checklist focus through clarifying questions"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: user_args
      source: cli_arg
      default: ""

# Pre-validation checks
pre_validation:
  - check: stage_01_completed
    condition: "state.checklist.current_stage == '01-initialization'"
    message: "Stage 01 (Initialization) must be completed first"
    recovery: "civyk-hatch checklist --stage=1"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: extract_signals
    instruction: "Extract domain keywords, risk indicators, stakeholder hints, and deliverables from user input and spec"
    output_variable: signals
  - step: 2
    type: input_required
    id: clarify_questions
    instruction: "Ask up to THREE contextual questions about scope, risk, depth, audience, and exclusions"
    prompt: "Clarifying checklist focus"
    blocking: true
  - step: 3
    type: action
    name: consolidate_requirements
    instruction: "Combine arguments and answers to derive checklist theme and focus areas"
    output_variable: checklist_focus

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
  forbidden_actions:
    - "Generate checklist before clarification is complete"
    - "Modify any files"
  read_only: true

# Post-validation checks
post_validation:
  - check: signals_extracted
    description: "Signals were extracted from user input and spec"
    severity: info
  - check: focus_determined
    description: "Checklist focus was determined"
    severity: error

# Output specification
output:
  state_update:
    checklist.current_stage: "02-clarify"
    checklist.checklist_focus: "{{checklist_focus}}"
  completion_command: "civyk-hatch update-stage checklist 02 --status completed"

# Next stage
next:
  stage: 3
  stage_id: "03"
  command: "civyk-hatch checklist --stage=3"
  is_terminal: false
version: 1.0.0
---

# Stage 2: Clarify Intent

## Purpose

Determine checklist focus through clarifying questions.

---

## Step 1: Extract Signals

From user input and spec, identify:

- Domain keywords (auth, UX, API, security)
- Risk indicators ("critical", "must", "compliance")
- Stakeholder hints ("QA", "review", "security team")
- Deliverables ("a11y", "rollback", "contracts")

---

## Step 2: Generate Questions (Max 3)

**[STOP: USER_INPUT_REQUIRED]**

Ask up to THREE contextual questions about:

- **Scope**: Include integration touchpoints or stay local?
- **Risk**: Which areas need mandatory gating checks?
- **Depth**: Lightweight sanity or formal release gate?
- **Audience**: Author only or peer review?
- **Exclusions**: Skip performance tuning this round?

**Question Format:**

| Option | Candidate | Why It Matters |
|--------|-----------|----------------|
| A | [option] | [impact] |
| B | [option] | [impact] |

MUST wait for user response before generating checklist.

---

## Step 3: Consolidate Requirements

Combine arguments + answers:

- Derive checklist theme (security, review, deploy, ux)
- Consolidate must-have items
- Map focus to category scaffolding
- Infer missing context from docs

---

## Defaults (if no interaction)

- Depth: Standard
- Audience: Reviewer (PR)
- Focus: Top 2 relevance clusters

---

## Output

```text

[ok] Intent clarified
  - Theme: [domain]
  - Focus areas: [list]
  - Audience: [author/reviewer/QA]
```

---

## NEXT

```bash
civyk-hatch checklist --stage=3 --feature-dir="{FEATURE_DIR}"
```
