---

# Stage identity per spec Section 6.1
stage: 2
stage_id: "02"
title: "Inconsistency Detection"
workflow: analyze
estimated_tokens: 4000

# Context specification
context:
  static:
    persona: "technical auditor performing systematic detection passes"
    purpose: "Execute detection passes to identify issues across artifacts"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: focus
      source: state
    - key: artifacts
      source: state

# Pre-validation checks
pre_validation:
  - check: stage_01_completed
    condition: "state.analyze.current_stage == '01-setup'"
    message: "Stage 01 (Setup) must be completed first"
    recovery: "civyk-hatch analyze --stage=1"
  - check: artifacts_exist
    condition: "artifacts were loaded in stage 01"
    message: "Artifacts must be loaded from stage 01"
    recovery: "civyk-hatch analyze --stage=1"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: build_models
    instruction: "Build semantic models: requirements inventory, user story inventory, task coverage mapping, constitution rule set"
    output_variable: semantic_models
  - step: 2
    type: action
    name: duplication_pass
    instruction: "Detect near-duplicate requirements and mark for consolidation"
    output_variable: duplication_findings
  - step: 3
    type: action
    name: ambiguity_pass
    instruction: "Flag vague adjectives and unresolved placeholders"
    output_variable: ambiguity_findings
  - step: 4
    type: action
    name: underspecification_pass
    instruction: "Detect requirements missing outcomes, user stories missing criteria, undefined references"
    output_variable: underspec_findings
  - step: 5
    type: action
    name: constitution_pass
    instruction: "Check for violations of MUST principles and missing mandated sections"
    output_variable: constitution_findings
  - step: 6
    type: action
    name: coverage_pass
    instruction: "Detect requirements without tasks and tasks without requirements"
    output_variable: coverage_findings
  - step: 7
    type: action
    name: inconsistency_pass
    instruction: "Detect terminology drift, entity mismatches, ordering contradictions, conflicting requirements"
    output_variable: inconsistency_findings
  - step: 8
    type: conditional
    name: guideline_pass
    instruction: "Check guideline compliance if guidelines were loaded"
    condition: "guidelines were loaded in stage 01"
    output_variable: guideline_findings

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
  forbidden_actions:
    - "Modify any files during analysis"
    - "Delete any files"
    - "Apply fixes automatically"
  read_only: true

# Post-validation checks
post_validation:
  - check: models_built
    description: "Semantic models were built"
    severity: error
  - check: passes_completed
    description: "All detection passes were executed"
    severity: error
  - check: findings_limited
    description: "Findings limited to 50 total"
    severity: warning

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

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

{{include:verification-rules.md}}

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

## Build Semantic Models

Create internal representations (do not output raw artifacts):

- **Requirements inventory**: Each requirement with stable key (e.g., "User can upload file" -> `user-can-upload-file`)
- **User story/action inventory**: Discrete user actions with acceptance criteria
- **Task coverage mapping**: Map each task to requirements (by keyword/explicit reference)
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements

## Detection Passes

Focus on high-signal findings. Limit to 50 findings total.

### A. Duplication Detection

- Identify near-duplicate requirements
- Mark lower-quality phrasing for consolidation

### B. Ambiguity Detection

- Flag vague adjectives (fast, scalable, secure, intuitive) lacking measurable criteria
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`)

### C. Underspecification

- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files/components not defined in spec/plan

### D. Constitution Alignment

- Any requirement or plan element conflicting with a MUST principle
- Missing mandated sections or quality gates from constitution

### E. Coverage Gaps

- Requirements with zero associated tasks
- Tasks with no mapped requirement/story
- Non-functional requirements not reflected in tasks

### F. Inconsistency

- Terminology drift (same concept named differently across files)
- Data entities in plan but absent in spec (or vice versa)
- Task ordering contradictions
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)

### G. Guideline Compliance (if guidelines loaded)

Report violations as:

- **CRITICAL**: Banned library specified in plan
- **HIGH**: Mandatory corporate library not specified
- **MEDIUM**: Architecture pattern deviates from guidelines
- **LOW**: Minor style/convention deviations

## Severity Assignment

- **CRITICAL**: Violates constitution MUST, missing core artifact, or requirement blocking baseline functionality
- **HIGH**: Duplicate/conflicting requirement, ambiguous security/performance attribute
- **MEDIUM**: Terminology drift, missing non-functional task coverage
- **LOW**: Style/wording improvements, minor redundancy

---

## Store Detection Findings

```text
# IF REPOIX_MODE != "none":
# [!] MANDATORY: Store findings after each detection pass
# Store after building semantic models
understand(
  action="store",
  scope="project",
  target="analyze-models",
  purpose="Semantic models from artifacts",
  importance="high",
  key_points=["requirements: <count>", "user_stories: <count>", "tasks: <count>", "rules: <count>"],
  gotchas=["<model_gaps>", "<parsing_issues>"],
  analysis="Models built. Requirements: <N>. Stories: <M>. Tasks: <K>. Constitution rules: <R>."
)

# Store after all detection passes complete
understand(
  action="store",
  scope="project",
  target="analyze-detection",
  purpose="Detection pass findings for Stage 3 report",
  importance="critical",
  key_points=["critical: <N>", "high: <N>", "medium: <N>", "low: <N>"],
  gotchas=["<blocking_issues>", "<constitution_violations>"],
  analysis="Detection complete. Findings: <critical>C/<high>H/<medium>M/<low>L. Top issues: <list>."
)

# IF REPOIX_MODE == "none":
# Cache unavailable — retain findings in session context for Stage 3 report generation
```

---

## NEXT

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