# How OpenSpec Handles Data Analysis: Discovery, Validation, and Synthesis

> Discover how OpenSpec analyzes specs as data using a three-stage pipeline: discovery, Zod validation, and synthesis. Validate changes and merge them efficiently.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: how-to-guide
- Published: 2026-06-28

---

**OpenSpec treats specifications as structured data, analyzing markdown artifacts through a three-stage pipeline—discovery, Zod schema validation with delta-spec extraction, and workflow-driven synthesis—to validate changes and merge them into the main spec tree.**

The Fission-AI/OpenSpec repository reimagines **data analysis** for software specifications. Instead of traditional statistical processing, OpenSpec analyzes markdown artifacts and metadata to understand what is changing, validate those changes against RFC 2119 standards, and drive automated workflows. This article examines the complete data analysis pipeline, from repository discovery to the final archive merge.

## The Three Stages of OpenSpec Data Analysis

OpenSpec structures its **data analysis** into three distinct architectural stages that transform raw markdown files into validated, actionable system specifications.

### Stage 1: Discovery and ID Collection

The analysis begins in [`src/utils/item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/item-discovery.ts), where the system scans the repository to locate active changes, spec files, and archived changes. Functions like `getActiveChangeIds`, `getSpecIds`, and `getArchivedChangeIds` walk the `openspec/changes` and `openspec/specs` directories, returning sorted identifiers that serve as the catalog for subsequent analysis.

```typescript
import { getActiveChangeIds } from './src/utils/item-discovery.js';
const activeIds = await getActiveChangeIds(); 
// → ['add-dark-mode', 'fix-auth-bug']

```

### Stage 2: Validation and Delta-Spec Analysis

Once discovered, artifacts are parsed and validated using **Zod** schemas defined in [`src/core/zod-issues.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/zod-issues.ts). The system validates required fields, checks for well-formed **RFC 2119** keywords (SHALL, MUST, SHOULD), and extracts *delta specs*—sections describing what is ADDED, MODIFIED, or REMOVED. This stage references [`schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml) for artifact dependencies and produces a structured view of changes that can be reasoned about programmatically.

### Stage 3: Workflow-Driven Synthesis

The verified delta-spec data feeds into the built-in *verify-change* and *archive-change* workflow templates. The [`src/core/templates/workflows/verify-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/verify-change.ts) workflow surfaces a "spec analysis" summary (e.g., "Delta spec analysis: X added requirements, Y modified"), while [`src/core/templates/workflows/archive-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts) performs a deterministic merge: ADDED sections append, MODIFIED sections replace, and REMOVED sections delete from the main spec tree.

## Implementing the Data Analysis Pipeline

The practical implementation follows a four-step process that moves from file discovery to permanent integration.

### Step 1: Collect Data IDs

The discovery utilities catalog all available specifications and changes, providing the engine with structured data to operate on.

### Step 2: Parse and Validate Artifacts

Each markdown artifact is read via [`src/utils/file-system.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/file-system.ts) and parsed against the schema. The validation extracts delta-spec blocks and ensures compliance with formatting standards.

```typescript
import { readFile } from './src/utils/file-system.js';
import { ChangeMetadataSchema } from './src/core/change-metadata/index.js';

const specContent = await readFile('openspec/changes/add-dark-mode/specs/ui/spec.md');
const validation = ChangeMetadataSchema.safeParse({ spec: specContent });
if (!validation.success) throw new Error('Invalid spec format');

```

### Step 3: Generate Analysis Summaries

Workflow templates embed placeholders like "Delta spec analysis: <include the analyzed delta spec summary>". When executed, the engine replaces these with concise summaries indicating the scope of changes.

```typescript
import { runWorkflow } from './src/core/templates/workflows/verify-change.js';
await runWorkflow({ changeId: 'add-dark-mode' });
// Output: "Delta spec analysis: 2 added requirements, 1 modified scenario."

```

### Step 4: Merge on Archive

The `archive-change` workflow consumes the delta-spec analysis and updates the source of truth. This deterministic merge ensures that approved changes become part of the canonical specification set.

```typescript
import { archiveChange } from './src/core/templates/workflows/archive-change.js';
await archiveChange({ changeId: 'add-dark-mode' });
// Updates openspec/specs/ui/spec.md with the new requirements

```

## Core Source Files for Data Analysis

Understanding the **data analysis** architecture requires familiarity with these specific source files:

- **[`src/utils/item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/item-discovery.ts)** – Walks the repository to locate changes and specs, exposing `getActiveChangeIds`, `getSpecIds`, and `getArchivedChangeIds` as the primary data collection functions.

- **[`src/utils/file-system.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/utils/file-system.ts)** – Abstracts filesystem operations for reading and writing markdown artifacts during the analysis pipeline.

- **[`src/core/zod-issues.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/zod-issues.ts)** – Central validation logic that enforces schema correctness before any analysis proceeds.

- **[`src/core/templates/workflows/verify-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/verify-change.ts)** – Generates human-readable analysis summaries used during the verification stage.

- **[`src/core/templates/workflows/archive-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts)** – Consumes delta-spec analysis to merge changes into the main spec set, updating the source of truth.

- **[`docs/concepts.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md)** – Documents the delta-spec concept that underlies the entire data analysis approach.

- **[`schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)** – Defines the artifact dependencies and structure that guide the analysis pipeline.

## Summary

- OpenSpec approaches **data analysis** by treating specifications, change artifacts, and metadata as structured data rather than performing traditional statistical processing.
- The analysis pipeline consists of three stages: **Discovery** ([`item-discovery.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/item-discovery.ts)), **Validation and Delta-Spec Analysis** ([`zod-issues.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/zod-issues.ts)), and **Workflow-Driven Synthesis** ([`verify-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/verify-change.ts) and [`archive-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/archive-change.ts)).
- **Delta-spec analysis** extracts ADDED, MODIFIED, and REMOVED sections to create structured, actionable summaries of what is changing in the system.
- The `archive-change` workflow performs deterministic merges to update the source of truth, while optional telemetry tracks metrics without interfering with the primary pipeline.

## Frequently Asked Questions

### What is delta-spec analysis in OpenSpec?

Delta-spec analysis is the process of extracting sections marked as ADDED, MODIFIED, or REMOVED from markdown artifacts to understand exactly what is changing in the system. This analysis produces structured summaries such as "3 added requirements, 2 modified scenarios" that drive workflow decisions and validation checks.

### How does OpenSpec validate specification data?

OpenSpec uses **Zod** schemas implemented in [`src/core/zod-issues.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/zod-issues.ts) to validate markdown artifacts against the schema defined in [`schemas/spec-driven/schema.yaml`](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml). The validation checks for required fields and proper **RFC 2119** keyword usage (SHALL, MUST, SHOULD) before accepting data into the analysis pipeline.

### What is the difference between the verify-change and archive-change workflows?

The **verify-change** workflow ([`src/core/templates/workflows/verify-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/verify-change.ts)) analyzes and validates changes while generating human-readable summaries for review. The **archive-change** workflow ([`src/core/templates/workflows/archive-change.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/archive-change.ts)) consumes that analysis to permanently merge delta specs into the main spec tree, updating the source of truth through deterministic ADD, MODIFY, and REMOVE operations.

### Does OpenSpec collect telemetry during data analysis?

Yes, OpenSpec optionally collects lightweight telemetry about how many changes are created, verified, and archived. This telemetry is stored in the user's data directory and can be queried for metrics, but it never interferes with the primary spec-analysis pipeline.