---

# Stage identity per spec Section 6.1
stage: 3
stage_id: "03"
title: "Generate Report"
workflow: analyze
estimated_tokens: 1500

# Context specification
context:
  static:
    persona: "technical auditor producing actionable analysis report"
    purpose: "Generate structured analysis report with findings and recommendations"
  dynamic:
    - key: feature_dir
      source: cli_arg
    - key: findings
      source: state
    - key: semantic_models
      source: state

# Pre-validation checks
pre_validation:
  - check: stage_02_completed
    condition: "state.analyze.current_stage == '02-detection'"
    message: "Stage 02 (Detection) must be completed first"
    recovery: "civyk-hatch analyze --stage=2"
  - check: findings_exist
    condition: "findings were collected in stage 02"
    message: "Detection findings must exist from stage 02"
    recovery: "civyk-hatch analyze --stage=2"

# Execution flow with step types
execution_flow:
  - step: 1
    type: action
    name: compile_report
    instruction: "Compile findings into structured Markdown report with findings table"
    output_variable: findings_report
  - step: 2
    type: action
    name: generate_coverage
    instruction: "Generate coverage summary table showing requirements to tasks mapping"
    output_variable: coverage_table
  - step: 3
    type: action
    name: list_constitution
    instruction: "List constitution alignment issues separately"
    output_variable: constitution_issues
  - step: 4
    type: action
    name: list_unmapped
    instruction: "List unmapped tasks with no requirement"
    output_variable: unmapped_tasks
  - step: 5
    type: action
    name: calculate_metrics
    instruction: "Calculate and report analysis metrics"
    output_variable: metrics
  - step: 6
    type: action
    name: provide_actions
    instruction: "Provide next action recommendations based on findings"
    output_variable: recommendations
  - step: 7
    type: input_required
    id: remediation_offer
    instruction: "Offer to suggest concrete remediation edits for top N issues"
    prompt: "Would you like me to suggest concrete remediation edits for the top N issues?"
    blocking: false

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Write
    - Grep
    - Glob
  forbidden_actions:
    - "Apply remediation edits automatically"
    - "Hallucinate missing sections"
  read_only: false

# Post-validation checks
post_validation:
  - check: report_generated
    description: "Analysis report was generated"
    severity: error
  - check: metrics_calculated
    description: "Analysis metrics were calculated"
    severity: error
  - check: recommendations_provided
    description: "Next action recommendations were provided"
    severity: warning

# Output specification
output:
  state_update:
    analyze.status: "completed"
    analyze.current_stage: "03-report"
  completion_command: "civyk-hatch update-stage analyze 03 --status completed"
  artifacts:
    - type: report
      path: "{{feature_dir}}/analysis-report.md"
      description: "Cross-artifact consistency analysis report"

# Next stage
next:
  is_terminal: true
version: 1.0.0
---

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

## Produce Compact Analysis Report

Output a Markdown report with the following structure:

### Specification Analysis Report

| ID | Category | Severity | Location(s) | Summary | Recommendation |
| ---- | ---------- | ---------- | ------------- | --------- | ---------------- |
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |

(One row per finding; generate stable IDs prefixed by category initial.)

### Coverage Summary Table

| Requirement Key | Has Task? | Task IDs | Notes |
| ----------------- | ----------- | ---------- | ------- |

### Constitution Alignment Issues

(List any violations)

### Unmapped Tasks

(List tasks with no mapped requirement/story)

### Metrics

- Total Requirements
- Total Tasks
- Coverage % (requirements with >=1 task)
- Ambiguity Count
- Duplication Count
- Critical Issues Count

## Provide Next Actions

- If CRITICAL issues exist: Recommend resolving before `civyk-hatch implement`
- If only LOW/MEDIUM: User may proceed, provide improvement suggestions
- Suggest commands: `civyk-hatch specify --feature "refined"`, `civyk-hatch plan --constraints "new"`

## Offer Remediation

Ask: "Would you like me to suggest concrete remediation edits for the top N issues?"

(Do NOT apply edits automatically - this is read-only analysis)

---

## Operating Constraints

**ANALYSIS-ONLY**: Do not modify any source or spec files. Write only the analysis report artifact (`{{feature_dir}}/analysis-report.md`).

**Constitution Authority**: The project constitution is **non-negotiable**. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks-not dilution of the principle.

## Operating Principles

- **Minimal high-signal tokens**: Focus on actionable findings
- **Progressive disclosure**: Load artifacts incrementally
- **Token-efficient output**: Limit to 50 rows; summarize overflow
- **Deterministic results**: Rerunning should produce consistent IDs and counts
- **NEVER modify source or spec files** (only write the report artifact)
- **NEVER hallucinate missing sections**
- **Prioritize constitution violations**
- **Report zero issues gracefully** with success report and statistics

---

## WORKFLOW COMPLETE

Analysis complete. Report generated.
