---
name: "step-08-finalize"
description: "Generate completion report, validate all artifacts, and provide next-step guidance"
nextStepFile: null
kind: "terminal"
---

# Step 8 of 8: Finalize Pipeline

**Goal:** Validate all output artifacts exist, generate a completion report, and provide guidance on next steps.

**Role:** Pipeline Orchestrator

---

## EXECUTION SEQUENCE

### 1. Validate All Artifacts

Check that ALL required output files exist:

1. **Requirements Analysis** — `{planning_artifacts}/requirements-analysis.md`
2. **Architecture Analysis** — `{planning_artifacts}/current-architecture-analysis.md`
3. **PRD** — `{planning_artifacts}/prd.md`
4. **Epics** — `{planning_artifacts}/epics.md`
5. **Architecture Design** — `{planning_artifacts}/architecture.md`

For each missing artifact, log a warning. If PRD or Epics are missing, this is a critical failure.

For each missing non-critical artifact (i.e., requirements-analysis.md, current-architecture-analysis.md, architecture.md), also append to `{run_warnings}`: `[step-08] Expected artifact missing at finalize: {artifact_path} — pipeline declared complete but downstream consumers may receive partial planning context` (see workflow.md "Warning Prefix-Tag Convention"). Critical missing artifacts (prd.md, epics.md) trigger the HALT path and do not need an additional `[step-08]` append since the pipeline does not write `pipeline-status.json` on HALT.

### 2. Run Completion Checklist

Load and evaluate: `./checklist.md`

Mark each item as passed or failed based on artifact verification.

### 2.4. Traceability Verification

**Goal:** Provide a lightweight cross-document traceability check that surfaces orphaned requirements/features before the pipeline declares complete. This complements (does not replace) the optional readiness check in section 2.5 — which is a deeper, multi-document audit — and gives a verdict even when the readiness skill is not installed.

**Procedure (best-effort; surfacing-only, never halts):**

1. Re-read `{req_file_path}`, `{planning_artifacts}/prd.md`, `{planning_artifacts}/epics.md`, and `{planning_artifacts}/architecture.md` from disk (fresh reads — do not rely on cached state from earlier steps).
2. Extract requirement/feature identifiers using best-effort heuristics:
   - `req.md` → distinct top-level functional requirements (e.g., `FR-`, `REQ-`, numbered list items in a "Requirements" section)
   - `prd.md` → declared features (often in a "Features" or "Functional Requirements" section)
   - `epics.md` → epic→story tree (story → AC mapping)
   - `architecture.md` → covered subsystems / components referenced by epic number
3. For each source identifier in `req.md`, attempt to find at least one downstream reference (PRD feature → epic → story → architecture coverage).
4. For each PRD feature, attempt to find at least one covering epic.
5. For each epic, verify at least one story exists with non-empty acceptance criteria (this duplicates the step-06 in-flight check but re-asserts at finalize against the on-disk state).
6. For any orphan (requirement with no PRD feature, PRD feature with no epic, epic with no story, epic not addressed by architecture):
   - Append to `{run_warnings}` using the canonical prefix: `[step-08] Traceability orphan detected: {orphan_kind} {orphan_id} has no downstream coverage in {next_artifact}` (see workflow.md "Warning Prefix-Tag Convention").
   - Continue — do NOT halt. The downstream readiness check (section 2.5) and `auto-story-pipeline` step-01 are responsible for gating execution.
7. If the identifier extraction is unreliable (e.g., the documents do not use a consistent ID scheme), append to `{run_warnings}` exactly one summary entry: `[step-08] Traceability verification skipped due to missing identifier conventions in source documents — manual review recommended` and proceed. This avoids generating false-positive orphan warnings on documents that simply do not use identifier conventions.

**Why this lives at step-08:** The checklist.md lists "Requirements Traceability", "Epic Coverage", "Story Completeness", and "No Orphaned Requirements" under Quality Validation, but prior versions of this step never executed these checks — they were aspirational. This section makes them operational without introducing a separate gating step (which would inflate the pipeline to 9 steps and break the documented `N/8` rendering in section 3). The check is intentionally best-effort and surface-only so it remains useful even on greenfield projects where ID conventions are still being established.

### 2.5. Optional Implementation Readiness Check

If `skill:xiaoma-check-implementation-readiness` exists (verified non-blocking in step-01), invoke the `xiaoma-check-implementation-readiness` skill to perform a cross-document alignment audit:

- **Inputs:** `{planning_artifacts}/prd.md`, `{planning_artifacts}/epics.md`, `{planning_artifacts}/architecture.md`, `{planning_artifacts}/current-architecture-analysis.md`
- **CRITICAL PIPELINE MODE INSTRUCTIONS:** This is running in automated pipeline mode — do NOT pause for user input. When any step presents a menu, automatically select **C (Continue)** to proceed.
- **Output:** Capture the readiness verdict (READY / GAPS / BLOCKED) and any flagged gaps. Record this verdict for the completion report.
- **If verdict is BLOCKED:** Set `{readiness_status}` = "blocked" and add the blockers to the `warnings` array (section 4). Do NOT halt the pipeline — readiness check is advisory; the human reviewer decides whether to proceed.
  - For each blocker reported by the readiness check, append to `{run_warnings}`: `[step-08] Implementation-readiness BLOCKED: {blocker_description}` (see workflow.md "Warning Prefix-Tag Convention")
- **If verdict is GAPS:** Set `{readiness_status}` = "gaps"; proceed.
  - For each gap reported, append to `{run_warnings}`: `[step-08] Implementation-readiness GAPS: {gap_description}`
- **If verdict is READY:** Set `{readiness_status}` = "ready"; proceed (no append needed).
- **If the skill is not installed:** Set `{readiness_status}` = "not_checked" and continue.
  - This branch was already flagged at step-01 (see workflow.md prefix-tag dictionary `[step-01]` row); do NOT double-append here.

### 3. Generate Completion Report

Set `{steps_completed}` = 8 and `{pipeline_status}` = "complete" now, before printing, so the report reflects the final accurate values.

**Output:**

```
═══════════════════════════════════════════════════
  Auto Requirements Pipeline — COMPLETE
═══════════════════════════════════════════════════

Project: {project_name}
Date: {date}
Steps Completed: {steps_completed}/8

📄 Output Artifacts:
  ✅/❌ {planning_artifacts}/requirements-analysis.md
  ✅/❌ {planning_artifacts}/current-architecture-analysis.md
  ✅/❌ {planning_artifacts}/prd.md
  ✅/❌ {planning_artifacts}/epics.md
  ✅/❌ {planning_artifacts}/architecture.md

Pipeline Status: {pipeline_status}
Implementation Readiness: {readiness_status}

═══════════════════════════════════════════════════
```

### 4. Generate Machine-Readable Status File

Write machine-readable status to: `{planning_artifacts}/pipeline-status.json`

**Warnings serialization (consumer of `{run_warnings}`)**: Read the `{run_warnings}` accumulator as built up by step-01 through step-07 plus this step's section 1, section 2.4, and section 2.5 appends. Write the list **as-is** into the JSON `warnings[]` field below — do not strip prefix tags, do not reorder, do not de-duplicate. Empty list serializes as `[]`. The auto-full-pipeline's `step-05-finalize` later wraps each entry with `[phase-1]` when aggregating into `full-pipeline-status.json`, so the original `[step-NN]` tag must be preserved here. See workflow.md "Warning Prefix-Tag Convention" for the canonical prefix dictionary.

*(Historical note: prior versions of this step said "collect all halts and warnings recorded during the pipeline run" but did not specify a concrete accumulator. The L-series refit introduces `{run_warnings}` as the single source of truth, mirroring the I-series convention in auto-story-pipeline. Steps 01–07 are the producers; this step is the sole consumer for the success path. Hard-HALT paths (e.g., a delegated workflow missing in step-01, PRD validation exceeded max iterations in step-05) MAY append a `[step-NN]` entry before halting, per workflow.md Rules item 5, but those entries are not consumed because this step never executes when an earlier hard HALT fires.)*

```json
{
  "pipeline": "auto-requirements-pipeline",
  "date": "{date}",
  "project": "{project_name}",
  "status": "complete",
  "readiness_status": "{readiness_status}",
  "steps_completed": 8,
  "artifacts": {
    "requirements_analysis": "{planning_artifacts}/requirements-analysis.md",
    "architecture_analysis": "{planning_artifacts}/current-architecture-analysis.md",
    "prd": "{planning_artifacts}/prd.md",
    "epics": "{planning_artifacts}/epics.md",
    "architecture": "{planning_artifacts}/architecture.md"
  },
  "iterations": {
    "analysis": {analysis_iteration},
    "architecture": {architecture_iteration},
    "validation": {validation_iteration}
  },
  "warnings": {run_warnings}
}
```

The `warnings` field is the full `{run_warnings}` list rendered as a JSON array of strings (i.e., expand `{run_warnings}` in-place as a JSON array — do NOT wrap the placeholder in quotes). If no warnings were captured, the list is empty and the field serializes as `[]`. Example concrete value (success path with three prefix-tagged warnings):

```json
"warnings": [
  "[step-01] No src/ directory found at project root — architecture analysis (step-03) may produce a sparse current-architecture-analysis.md",
  "[step-02] Requirements-analysis quality self-check exceeded max retries (3 iterations) — proceeding with remaining gaps documented under 'Known Limitations' in requirements-analysis.md",
  "[step-08] Implementation-readiness GAPS: prd.md acceptance criterion AC-FR-3.2 has no matching epic story"
]
```

This enables downstream tools (including the Auto Story Pipeline) to check pipeline status programmatically. The Auto Story Pipeline's step-01 section 1 ("Requirements Pipeline Status") reads the `status` field only — it surfaces a non-blocking WARNING and continues when `status != "complete"`, and never reads `readiness_status`. The `readiness_status` field is consumed separately by `auto-full-pipeline/step-05-finalize.md` (and `auto-full-pipeline/step-01-init-and-validate.md`) when this pipeline runs inside the full pipeline.

### 5. Provide Next Steps

**Output:**

```
🔜 Recommended Next Steps:

1. Review generated artifacts in {planning_artifacts}/
2. Run Sprint Planning (SP) to organize stories into sprints
3. Run Auto Story Pipeline to begin implementation

Available commands:
  - SP (Sprint Planning) — Organize epics/stories into sprints
  - ASP (Auto Story Pipeline) — Automated story development lifecycle
```

### 6. Pipeline Complete

**Pipeline execution is COMPLETE. HALT.**

---

## SUCCESS METRICS

- All 5 output artifacts verified
- Machine-readable `pipeline-status.json` generated
- Completion report generated
- Next steps provided
- Pipeline status set to "complete"
- `{run_warnings}` serialized as-is into `pipeline-status.json.warnings[]` with `[step-NN]` prefix tags preserved (empty list `[]` is valid); the field is downstream-aggregator-ready for `auto-full-pipeline`'s `[phase-1]` wrap

## FAILURE MODES

- Missing critical artifacts (PRD, Epics)
- Not providing completion report
- Not suggesting next steps
- Silently dropping `{run_warnings}` (writing `warnings: []` when the accumulator had entries) — would defeat the L-series prefix-tag plumbing and disrupt the downstream `[phase-1]` aggregation in `auto-full-pipeline/step-05-finalize`
- Stripping prefix tags from individual warning strings — downstream consumers pattern-match on `[step-NN]` and `[phase-1]` prefixes, so removing them breaks the aggregation contract