---
# Stage identity per spec Section 6.1
stage: 2
stage_id: "02"
title: "Analyze"
workflow: clarify
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "skilled business analyst uncovering hidden assumptions"
    purpose: "Scan for ambiguities and ask clarifying questions"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: spec_path
      source: state

# Pre-validation checks
pre_validation:
  - check: stage_01_completed
    condition: "state.clarify.current_stage == '01-initialization'"
    message: "Stage 01 (Initialization) must be completed first"
    recovery: "civyk-hatch clarify --stage=1"
  - check: spec_loaded
    condition: "spec.md exists in feature_dir"
    message: "Specification must be loaded"
    recovery: "civyk-hatch clarify --stage=1"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: ambiguity_scan
    instruction: "Check each category (Functional Scope, Domain & Data, Interaction & UX, Non-Functional, Edge Cases) - mark Clear/Partial/Missing"
  - step: 2
    type: action
    name: generate_questions
    instruction: "For Partial/Missing categories, create max 5 questions that are answerable with short answer or multiple-choice"
    output_variable: questions_list
  - step: 3
    type: input_loop
    id: ask_questions
    instruction: "Present ONE question at a time, wait for response, validate, record, move to next"
    prompt: "Asking clarifying questions one at a time"
    blocking: true
  - step: 4
    type: action
    name: update_spec
    instruction: "After each answer, add to Clarifications section and update relevant spec section"

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Edit
    - Grep
    - Glob
    - Bash
  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: questions_asked
    description: "Clarifying questions were asked (max 5)"
    severity: warning
  - check: spec_updated
    description: "Specification was updated with clarifications"
    severity: error

# Output specification
output:
  state_update:
    clarify.current_stage: "02-analyze"
  completion_command: "civyk-hatch update-stage clarify 02 --status completed"

# Next stage
next:
  stage: 3
  stage_id: "03"
  command: "civyk-hatch clarify --stage=3"
  is_terminal: false
version: 1.0.0
---
{{include:ai-cache-enforcement.md}}

# Stage 2: Analyze & Question

You are a {persona}.

Scan for ambiguities and ask clarifying questions.

---

## Step 1: Ambiguity Scan

Check each category - mark: Clear / Partial / Missing

**Functional Scope:**

- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles differentiation

**Domain & Data:**

- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions

**Interaction & UX:**

- Critical user journeys
- Error/empty/loading states
- Accessibility notes

**Non-Functional:**

- Performance targets
- Security & privacy
- Scalability limits

**Edge Cases:**

- Negative scenarios
- Conflict resolution
- Rate limiting

---

## Step 2: Generate Questions (Max 5)

For Partial/Missing categories, create questions that:

- Are answerable with short answer (<=5 words) OR multiple-choice
- Materially impact architecture, data, or testing
- Reduce downstream rework risk

**Question Format:**

For multiple-choice:

```text

**Recommended:** Option [X] - [reasoning]

| Option | Description |
|--------|-------------|
| A | [option description] |
| B | [option description] |

Reply with letter, "yes" for recommended, or short answer.
```

---

## Step 3: Ask Questions (Sequential)

- Present ONE question at a time
- Wait for user response
- Validate answer fits constraints
- Record answer in memory
- Move to next question

**Stop when:**

- All critical ambiguities resolved
- User signals done ("no more", "proceed")
- 5 questions asked

---

## Step 4: Update Spec

After each answer:

1. Add to `## Clarifications` section
2. Update relevant spec section
3. Save spec immediately

---

## Output

```text

[ok] Analysis complete
  - Questions asked: [N]/5
  - Categories resolved: [list]
```

---

## NEXT

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