SDS-025: Prompt Evolution Engine

Type

Software Design Specification - Prompt Engineering / Core

Status

Proposed

Implements

• ADR-026: Cognitive Supply Chain
• ADR-025: MECE Cognitive Architecture

1. System Overview

The Prompt Evolution Engine implements Lamarckian Evolution for prompt files. Traits acquired during execution (lessons learned) are passed down to the next generation (updated prompts).

This creates an Anti-Fragile System that gains intelligence from every error.

2. Core Isomorphism: Prompt Training ≅ Model Training

3. The Evolution Protocol

3.1 Execution → Validation → Reflection → Commit

sequenceDiagram
    participant Dev as Developer
    participant Task as Task Prompt
    participant LLM as LLM Engine
    participant Test as Test Runner
    participant Groom as Groomer Agent
    participant Git as Version Control

    Dev->>Task: Execute task.prompt.md
    Task->>LLM: Generate Code
    LLM-->>Test: Output: feature.ts
    Test->>Test: Run Tests
    alt Tests Pass
        Test-->>Dev: ✓ Commit
    else Tests Fail
        Test->>Groom: error.log
        Groom->>Groom: Analyze Root Cause
        Groom->>Task: Propose Constraint Update
        Groom-->>Git: PR: Update task.prompt.md
        Git-->>Dev: Review & Merge
    end

3.2 The Memetic Evolution Log

Each prompt file contains an append-only section for learning:

1
2
3
4
5
6
7
8
... [Standard Instructions] ...

# 🧬 MEMETIC EVOLUTION LOG (Auto-Generated)
<!-- The AI appends specific failure modes here. -->
- [2025-10-12]: Failed to implement error handling for API 429. 
  FIX: Always wrap fetch calls in the `retryWrapper` utility.
- [2025-10-14]: Hallucinated a 'User' type. 
  FIX: Import types strictly from `@/types/index.d.ts`.

3.3 Consolidation (Garbage Collection)

When the Evolution Log exceeds threshold items (default: 10), trigger consolidation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
def consolidate_prompt(prompt: PromptFile, threshold: int = 10) -> PromptFile:
    """Rewrite instructions to incorporate lessons, then clear log."""
    if len(prompt.evolution_log) < threshold:
        return prompt
    
    consolidated = groomer.synthesize(
        original_instructions=prompt.instructions,
        lessons=prompt.evolution_log
    )
    
    return PromptFile(
        instructions=consolidated,
        evolution_log=[]  # Clear after consolidation
    )

4. Four-Vector Grooming Operations

The Groomer operates on a Cartesian plane of meaning with two orthogonal axes:

• Scope: General ↔ Special
• Resolution: Abstract ↔ Concrete

4.1 The Four Vectors

4.2 The Aristotelian Pivot Rule

CRITICAL: You cannot move diagonally (opposites).

To transform from [Abstract/General] to [Concrete/Special]:

1. First Specialize (narrow the domain)
2. Then Concretize (add specifics)

This prevents hallucination from large semantic jumps.

5. Hyper-Parameters

Configured in .github/config/agent-defaults.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "economy": {
    "constraintBudget": 20,
    "decayRatePerCycle": 0.1,
    "consolidationThreshold": 10
  },
  "grooming": {
    "vectors": ["concretization", "abstraction", "specialization", "generalization"],
    "pivotRequired": true,
    "maxChangePerCycle": 3
  },
  "training": {
    "patience": 3,
    "batchSize": 1,
    "earlyStoppingThreshold": 5
  }
}

6. The Cognitive Economy Model

6.1 Preventing Overfitting via Market Dynamics

6.2 The Attention Tax

When adding a new constraint:

1. Check budget
2. If Over Budget: Identify lowest-value constraint and delete it
3. Value = (Activation Frequency) / (Token Cost)

1
2
3
4
5
6
7
8
9
10
11
12
def should_add_constraint(new_constraint: Constraint, prompt: PromptFile) -> bool:
    if prompt.constraint_count < BUDGET:
        return True
    
    # Find lowest value constraint
    weakest = min(prompt.constraints, key=lambda c: c.activation_count / c.token_cost)
    
    if new_constraint.expected_value > weakest.value:
        prompt.remove_constraint(weakest)
        return True
    
    return False

6.3 Synaptic Pruning (The Sunset Clause)

Every constraint has:

• timestamp: When added
• strength: Starts at 100%, decays over time
• activation_count: How often triggered

Weekly cycle: Remove constraints with strength < 20%.

7. Jump-Start Protocol (Seeding)

7.1 The Empty Seed

Start with maximum abstraction:

1
2
3
You are an expert software engineer. 
Write high-quality code for this task. 
Follow standard best practices.

7.2 The Stress Run (Accelerated Evolution)

1. Run generation for all WBS tasks
2. It will fail (generic prompts produce generic garbage)
3. Collect all linter/compiler errors
4. Feed errors to Groomer Agent
5. Groomer applies CONCRETIZATION and SPECIALIZATION vectors

Result: Months of “learning from mistakes” compressed into one synthetic run.

8. API Contract

8.1 Trigger Evolution

1
POST /evolution/trigger

Request:

1
2
3
4
5
6
7
8
{
  "prompt_path": ".github/prompts/phase-3/01-test-fabrication.prompt.md",
  "error_log": "TypeError: Cannot read property 'id' of undefined...",
  "context": {
    "test_file": "auth.test.ts",
    "commit_sha": "abc123"
  }
}

Response:

1
2
3
4
5
6
7
{
  "evolution_id": "uuid",
  "proposed_vector": "SPECIALIZATION",
  "proposed_change": "Add null check requirement for user objects",
  "confidence": 0.85,
  "requires_approval": true
}

8.2 Apply Evolution

1
POST /evolution/{id}/apply

8.3 Consolidate Prompt

1
POST /evolution/consolidate

9. Integration Points

10. Related Specifications

• ADR-026: Cognitive Supply Chain
• SDS-026: Semantic Groomer Service
• SDS-023: Evolutionary Kernel Service