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

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, 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.

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. 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 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 workflow surfaces a "spec analysis" summary (e.g., "Delta spec analysis: X added requirements, Y modified"), while 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 and parsed against the schema. The validation extracts delta-spec blocks and ensures compliance with formatting standards.

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: ". When executed, the engine replaces these with concise summaries indicating the scope of changes.

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.

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 – Walks the repository to locate changes and specs, exposing getActiveChangeIds, getSpecIds, and getArchivedChangeIds as the primary data collection functions.

• src/utils/file-system.ts – Abstracts filesystem operations for reading and writing markdown artifacts during the analysis pipeline.

• src/core/zod-issues.ts – Central validation logic that enforces schema correctness before any analysis proceeds.

• src/core/templates/workflows/verify-change.ts – Generates human-readable analysis summaries used during the verification stage.

• 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 – Documents the delta-spec concept that underlies the entire data analysis approach.

• 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), Validation and Delta-Spec Analysis (zod-issues.ts), and Workflow-Driven Synthesis (verify-change.ts and 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 to validate markdown artifacts against the schema defined in 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) analyzes and validates changes while generating human-readable summaries for review. The archive-change workflow (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}