---
# Stage identity per spec Section 6.1
stage: 3
stage_id: "03"
title: "Research"
workflow: plan
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "senior software architect designing pragmatic systems"
    purpose: "Create research.md with technical decisions and fill initial plan sections"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: repoix_mode
      source: tool_state

# Pre-validation checks
pre_validation:
  - check: stage_02_completed
    condition: "state.plan.current_stage == '02-setup'"
    message: "Stage 02 (Setup) must be completed first"
    recovery: "civyk-hatch plan --stage=2"
  - check: plan_template_exists
    condition: "plan.md exists in feature_dir"
    message: "plan.md template must exist"
    recovery: "civyk-hatch plan --stage=2"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: check_cache
    instruction: "Check AI context cache for cached understanding of relevant modules"
  - step: 2
    type: action
    name: extract_unknowns
    instruction: "Review specification for items needing clarification or research"
  - step: 3
    type: action
    name: execute_research
    instruction: "Search for authoritative sources, evaluate options, document findings"
  - step: 4
    type: action
    name: validate_dependencies
    instruction: "Validate dependencies against Artifactory"
  - step: 5
    type: action
    name: create_research_md
    instruction: "Create research.md with all technical decisions documented"
  - step: 6
    type: action
    name: fill_plan_chunk1
    instruction: "Fill Summary, Technical Context, and Constitution Check sections in plan.md"
  - step: 7
    type: action
    name: validate_chunk1
    instruction: "Verify all sections are filled with no remaining placeholders"

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Edit
    - Write
    - Grep
    - Glob
    - Bash
    - WebFetch
  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: research_created
    description: "research.md was created with all decisions"
    severity: error
  - check: summary_filled
    description: "Summary section was filled"
    severity: error
  - check: tech_context_filled
    description: "Technical Context section was filled"
    severity: error
  - check: constitution_checked
    description: "Constitution Check was completed"
    severity: warning

# Output specification
output:
  state_update:
    plan.current_stage: "03-research"
  completion_command: "civyk-hatch update-stage plan 03 --status completed"

# Next stage
next:
  stage: 4
  stage_id: "04"
  command: "civyk-hatch plan --stage=4"
  is_terminal: false
version: 1.0.0
---
# Stage 3: Research & Initial Plan Sections

You are a {persona}.

1. Create research.md with technical decisions
2. Fill initial plan.md sections (Summary, Technical Context, Constitution Check)

---

## Tools (if REPOIX_MODE != "none")

{{include:plan-civyk-repoix-discovery.md}}

---

## Step 1: Check Cache

Before researching external solutions, check cached understanding and discover existing codebase patterns:

```text
# Check what's cached from earlier stages
understand(action="stats", limit=50)
# Use cached coverage to decide: full discovery vs targeted gap-filling
```

- Use civyk-repoix MCP/CLI to discover existing utils, base classes, methods, patterns
- Use `quality(action="duplicates", source_only=true)` to find similar implementations you can extend
- Use `symbol(action="similar", fqn=fqn)` to find related code when you identify a relevant symbol
- Prefer extending existing patterns over introducing new ones
- Consider edge cases in design decisions

**IF REPOIX_MODE == "none":** Manually explore codebase via file reading.

---

## Step 2: Extract Unknowns

Review the specification for:

- Items marked "NEEDS CLARIFICATION"
- Dependencies requiring best practices research
- Integrations requiring pattern research
- Technology choices not specified

---

## Step 3: Execute Research

For each unknown or technology choice:

1. Search for authoritative sources
2. Evaluate options and tradeoffs
3. Document findings

---

## Step 4: Validate Dependencies Against Artifactory

{{include:artifactory-validation.md}}

**When to validate:**

- After identifying required dependencies in Step 2
- Before finalizing technology choices in research.md

**Add to research.md:**

```markdown
## Dependency Validation

| Package | Version | Purpose | Artifactory Status |
|---------|---------|---------|-------------------|
| ... | ... | ... | [VERIFIED] / [NOT FOUND] / [SKIPPED] |

**Blocked Dependencies** (if any):
- `<package>`: Not found in Artifactory - alternative: `<alternative>`
```

---

## Step 5: Create research.md

Use the **Write tool** to create `{{feature_dir}}/research.md`:

```markdown
# Research: <feature name>

## Decision: [Topic 1]

**Chosen**: [what was selected]
**Rationale**: [why selected]
**Alternatives considered**: [what else evaluated]
**Sources**: [links/references]

## Decision: [Topic 2]

...
```

---

## Step 6: Fill Plan Sections (Chunk 1 of 3)

Edit `{{feature_dir}}/plan.md` to fill these sections:

### 6.1 Summary Section

Replace the `[Extract from feature spec...]` placeholder with:

- Primary requirement from spec
- Technical approach from research

### 6.2 Technical Context Section

Fill ALL fields, replacing `[...]` and `NEEDS CLARIFICATION`:

- Language/Version
- Primary Dependencies
- Storage
- Testing
- Target Platform
- Project Type
- Performance Goals
- Constraints
- Scale/Scope

### 6.3 Constitution Check Section

Validate spec against constitution principles. Fill the section with:

- Each principle from constitution.md
- Pass/fail status for each
- Notes on any violations

**IMPORTANT**: Do NOT leave any `[...]` placeholders in these sections.

---

## Step 7: Validate Chunk 1

Verify all sections are filled:

- [ ] research.md created with all decisions
- [ ] Summary section filled (no placeholders)
- [ ] Technical Context filled (no placeholders)
- [ ] Constitution Check completed

**IF violations found in Constitution Check**: Document in Complexity Tracking section.

---

## Output

```text
[ok] Research complete
  - Decisions: [N] documented
  - File: {{feature_dir}}/research.md
  - Plan sections filled: Summary, Technical Context, Constitution Check
```

---

## NEXT

```bash
civyk-hatch plan --stage=4 --feature-dir="{FEATURE_DIR}"
```
