---
# Stage identity
stage: 2
stage_id: "02"
title: "Spec & Clarify"
workflow: rapid
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "senior engineer writing a concise, precise specification"
    purpose: "Expand user intent into structured spec, self-clarify ambiguities via code analysis"
  dynamic:
    - key: intent
      source: cli_arg
    - key: tmp_dir
      source: cli_arg
    - key: repoix_mode
      source: tool_state

# Pre-validation checks
pre_validation:
  - check: stage_01_completed
    condition: "Stage 1 (Gate & Analyze) completed successfully"
    message: "Stage 1 must complete first"
    recovery: "civyk-hatch rapid --stage=1 --intent=\"{INTENT}\""

# Execution flow
execution_flow:
  - step: 1
    type: action
    name: research_domain
    instruction: "Use repoix to understand domain context for the intent"
  - step: 2
    type: action
    name: expand_spec
    instruction: "Expand intent into structured spec (What/Why/Where/How/Constraints/AC)"
  - step: 3
    type: action
    name: self_clarify
    instruction: "Analyze spec for ambiguities, resolve by examining code patterns"
  - step: 4
    type: action
    name: write_spec
    instruction: "Write spec.md to tmp_dir"

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
    - Write
  forbidden_actions:
    - "Modify any source files"
    - "Write files outside tmp_dir"
    - "Call civyk_hatch_update_stage (rapid workflow is stateless)"
  file_restrictions:
    allowed_paths:
      - "tmp/**"
    forbidden_paths:
      - "src/**"
      - "scripts/**"
      - ".env"
      - "**/*.key"
      - "**/credentials*"
  read_only: false

# Post-validation checks
post_validation:
  - check: spec_written
    description: "spec.md written to tmp_dir with What/Why/Where/How/Constraints/AC"
    severity: error
  - check: ambiguities_resolved
    description: "Ambiguities self-clarified via code analysis"
    severity: info

# Next stage
next:
  stage: 3
  stage_id: "03-plan-tasks"
  command: "civyk-hatch rapid --stage=3 --intent=\"{INTENT}\" --tmp-dir=\"{TMP_DIR}\""
  auto_continue: true
version: 1.0.0
---
# Stage 2: Spec & Clarify

You are a {persona}.

**Intent**: {{intent}}

## Step 1: Research Domain Context

{{include:rapid-repoix-discovery.md}}

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

Use civyk-repoix MCP/CLI to understand the domain context for this intent:

```text
understand(action="recall", target="<target_file>")  # Check cache before reading
search(action="symbols", query="<relevant_terms>", kind="function", limit=20)
file(action="symbols", path="<target_file>", include_private=true)
architecture(action="components")
quality(action="impact", fqn="<target_symbol>", depth=2, include_tests=true)  # Understand ripple effects
```

## Step 2: Expand Intent into Specification

Take user intent: "{{intent}}"

Write a structured, concise spec covering:

- **What**: Clear description of the change
- **Why**: Rationale and motivation
- **Where**: Files/modules affected (from repoix discovery)
- **How**: High-level implementation approach
- **Constraints**: From AGENTS.md, tech guidelines (loaded in Stage 1). **If** constitution was loaded in Stage 1, include all applicable constitutional principles here
- **Acceptance Criteria**: Testable conditions for completion

## Step 3: Self-Clarify

Analyze the spec for ambiguities — resolve using repoix:

1. **Underspecified areas** -> `search(action="symbols")` + `file(action="symbols")` to find existing patterns
2. **Conflicts with existing architecture** -> `architecture(action="components")` + `architecture(action="dependencies")` to understand structure
3. **Ambiguous requirements** -> ask user ONLY if cannot be inferred from code

Self-remediate everything possible. Minimize user interruptions.

## Step 4: Write Spec

Write the completed spec to: `{{tmp_dir}}/spec.md`

Format:

```markdown
# Spec: {title derived from intent}

## What
{change description}

## Why
{rationale}

## Where
{files and modules affected}

## How
{high-level approach}

## Constraints
{from project context}

## Acceptance Criteria
- [ ] {criterion 1}
- [ ] {criterion 2}
- [ ] ...
```
