How Seed Generation in Ouroboros Creates Immutable Specifications from Interview Data

Seed generation in Ouroboros converts BigBang interview transcripts into immutable specifications by enforcing an ambiguity threshold of 0.2, extracting structured requirements via LLM with the seed-architect prompt, and encapsulating them in a frozen Pydantic model that prevents any post-creation mutation.

The Q00/ouroboros repository implements a rigorous pipeline that transforms conversational requirements gathering into concrete, versioned artifacts. This process, known as Seed generation, ensures that only sufficiently clarified interview data becomes immutable specification objects that drive the entire workflow orchestration.

The Five-Phase Seed Generation Pipeline

The transformation from free-form interview to read-only specification follows a strict sequence implemented in src/ouroboros/bigbang/seed_generator.py.

Phase 1: Ambiguity Gating

Before any extraction occurs, the system validates the clarity of the interview data. The SeedGenerator.generate method (lines 150‑166) checks the AmbiguityScore against the constant AMBIGUITY_THRESHOLD defined in bigbang/ambiguity.py.

Only interviews with an overall ambiguity score ≤ 0.2 proceed to seed creation. This gate guarantees that vague or contradictory requirements cannot become immutable specifications, preventing technical debt from entering the workflow at the specification level.

Phase 2: Structured Extraction via LLM

Once ambiguity is cleared, the transcript undergoes structured extraction. The _build_interview_context method (lines 303‑322) renders the conversation into a single context string.

This context is sent to the LLM with the strict seed-architect system prompt, which mandates an exact plain-text format covering goals, constraints, and ontology. The response is sanitized via _preprocess_response and parsed by _parse_extraction_response (lines 504‑534) into a dictionary of requirement fields.

Phase 3: Metadata Provenance

Every seed carries an audit trail. During generation, the code constructs a SeedMetadata instance (lines 191‑199) that records:

• A unique UUID for the seed
• Creation timestamp
• Source interview ID
• The ambiguity score at creation time
• Parent seed link (for evolved specifications)

This metadata creates an immutable provenance chain linking the specification back to the exact conversation that produced it.

Phase 4: Immutable Model Construction

The parsed requirements are transformed into the concrete Pydantic model Seed defined in src/ouroboros/core/seed.py (lines 55‑78). All fields are declared with frozen=True, making the instance truly immutable—any attempt to modify an attribute raises a ValidationError.

The _build_seed method (lines 489‑558) assembles the model with two distinct sections:

• Immutable direction: Goal, constraints, and acceptance criteria that can never change
• Evolvable ontology: Structured domain knowledge that may only be refined through the reflection step

Phase 5: Persistent Storage

The finished Seed is serialized to YAML via save_seed (lines 691‑756), preserving the full immutable specification for the execution engine. The load_seed method enables retrieval of these specifications for replay or audit purposes.

Why Immutability Matters for Workflow Integrity

Immutability serves three critical functions in the Ouroboros architecture:

• Consistency across generations: Once stored, the orchestrator can replay any generation without risking specification drift or mutation side effects.
• Auditability: The combination of Seed data and SeedMetadata forms a complete provenance record, enabling forensic analysis of why a particular workflow path was taken.
• Safety: By freezing the "direction" component (goals, constraints, acceptance criteria), the system prevents accidental changes that could violate the original business requirements during long-running workflows.

Handling Evolution in Generation 2 and Beyond

When workflows proceed to later generations, the generate_from_reflect method (lines 178‑210) creates new seeds while preserving immutability guarantees.

This method mutates only the ontology section based on reflection insights, copying the parent's immutable direction fields unchanged. It establishes a strict lineage by setting the parent_seed_id in the new seed's metadata, creating an auditable chain of specification evolution without ever altering historical artifacts.

Practical Implementation Example

The following example demonstrates the complete flow from interview to immutable seed:

# ----------------------------------------------------------------------

# Example: generate a Seed from a completed interview

# ----------------------------------------------------------------------

from pathlib import Path
from ouroboros.bigbang.seed_generator import SeedGenerator
from ouroboros.bigbang.interview import InterviewEngine, InterviewState
from ouroboros.bigbang.ambiguity import AmbiguityScore
from ouroboros.providers.litellm_adapter import LiteLLMAdapter  # any LLMAdapter implementation

# 1️⃣  Run the interview (this would normally be interactive)

engine = InterviewEngine()
state: InterviewState = await engine.start_interview(
    initial_context="Build a CLI task manager"
)

# 2️⃣  Compute ambiguity (the engine already does this)

ambiguity: AmbiguityScore = await engine.compute_ambiguity(state)

# 3️⃣  Create the seed generator with an LLM adapter

generator = SeedGenerator(llm_adapter=LiteLLMAdapter())

# 4️⃣  Generate the immutable Seed (throws ValidationError if ambiguity > 0.2)

result = await generator.generate(state=state, ambiguity_score=ambiguity)

if result.is_ok:
    seed = result.value
    print("✅ Seed created – ID:", seed.metadata.seed_id)
    # 5️⃣  Persist to YAML (optional)

    await generator.save_seed(seed, Path("my_seed.yaml"))
else:
    print("❌ Seed generation failed:", result.error)

This implementation follows the exact control flow defined in SeedGenerator.generate and SeedGenerator._build_seed, ensuring the resulting artifact is immutable and ready for workflow execution.

Summary

• Seed generation transforms BigBang interview transcripts into immutable specifications through a five-phase pipeline: ambiguity gating, LLM extraction, metadata creation, frozen model construction, and YAML persistence.
• The 0.2 ambiguity threshold in bigbang/ambiguity.py acts as a quality gate, preventing unclear requirements from becoming seeds.
• The Seed Pydantic model uses frozen=True (defined in core/seed.py) to enforce runtime immutability, raising ValidationError on any modification attempt.
• Evolution is handled by generate_from_reflect, which creates new seeds with preserved parent lineage while keeping the original direction fields immutable.
• Complete auditability is maintained through SeedMetadata, which links every seed to its source interview and ambiguity score.

Frequently Asked Questions

What happens if the ambiguity score exceeds 0.2 during Seed generation?

The SeedGenerator.generate method rejects the operation and returns an error result. This prevents the creation of seeds from unclear or contradictory interview data, ensuring that only well-defined requirements enter the immutable workflow pipeline.

How does the Seed model enforce immutability at the code level?

The Seed class in src/ouroboros/core/seed.py declares all fields with Pydantic's frozen=True configuration. This generates a ValidationError at runtime if any code attempts to modify seed attributes after instantiation, providing compile-time and runtime guarantees of immutability.

Can a Seed be modified after it is created in Ouroboros?

No. Once instantiated, a Seed cannot be modified. To change requirements, the system creates a new Seed via generate_from_reflect, which copies the immutable direction from the parent while allowing ontology refinements. The original seed remains unchanged, preserving historical accuracy.

How does Seed generation handle requirements evolution across workflow generations?

The generate_from_reflect method creates a new seed that references the original via parent_seed_id in the metadata. It preserves the parent's immutable direction (goals and constraints) while updating only the ontology based on reflection insights, maintaining a strict lineage chain for audit purposes.

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