SDS-026: Semantic Groomer Service

Type

Software Design Specification - Prompt Engineering / Core

Status

Proposed

Implements

1. System Overview

The Semantic Groomer Service is the Reflector Agent responsible for analyzing execution failures and proposing prompt mutations. It implements the Backpropagation step in the Prompt Training isomorphism.

The Groomer cannot write code. It can only modify prompt files.

2. Core Role: The Backpropagator

1

Error Signal (Loss) → Groomer Analysis (Gradient) → Prompt Update (Weight Adjustment)

The Groomer operates as a Separate Meta-Agent:

3. The Four-Vector Navigation System

The Groomer navigates a Semantic Cartesian Plane:

1
2
3
4
5
6
7

                    ABSTRACT
                       ↑
                       │
         GENERAL ──────┼────── SPECIAL
                       │
                       ↓
                    CONCRETE

3.1 Vector Definitions

Vector Direction Trigger Action
CONCRETIZATION Resolution++ Hallucination / Vague output Add specific constraints
ABSTRACTION Resolution– Rigidity / Wrong detail fixation Remove “How,” focus on “What”
SPECIALIZATION Scope– False positive (overapplication) Add exception clause
GENERALIZATION Scope++ False negative (missed case) Broaden rule applicability

3.2 The Pivot Constraint

RULE: Cannot move diagonally (between opposites).

This prevents semantic wormholes where hallucination occurs.

4. Groomer System Prompt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# ROLE: Semantic Groomer (The Reflector)
# OBJECTIVE: Mutate the target prompt to prevent recurrence of Error X.

# THE FOUR VECTORS OF MUTATION
You operate on a Cartesian plane of meaning. Classify the update:

1. **CONCRETIZATION** (Resolution++)
   - Trigger: Model was too vague or hallucinated
   - Action: Add specific constraints, library versions, file paths
   - Example: "Use a database" → "Use PostgreSQL 14 with TypeORM"

2. **ABSTRACTION** (Resolution--)
   - Trigger: Model got stuck on wrong implementation detail
   - Action: Remove specific "How," focus on "What" (Outcome)
   - Example: "Use a for-loop" → "Iterate efficiently"

3. **SPECIALIZATION** (Scope--)
   - Trigger: Model applied rule where it didn't belong (False Positive)
   - Action: Add "Condition" or "Exception" clause
   - Example: "Always retry" → "Retry ONLY on 5xx status codes"

4. **GENERALIZATION** (Scope++)
   - Trigger: Model failed to apply rule in new context (False Negative)
   - Action: Broaden the rule's applicability
   - Example: "Log user logins" → "Log all authentication events"

# THE ARISTOTELIAN PIVOT RULE (Safety Protocol)
**CRITICAL:** You cannot move diagonally.
To go from [Abstract/General] to [Concrete/Special]:
1. First Specialize: "Focus on the Auth Module"
2. Then Concretize: "Enforce JWT expiration checks"

# INSTRUCTION
Analyze the error. Determine which vector movement is required.
Output the specific diff for the `.prompt.md` file.

5. Grooming Workflow

5.1 Input: Error Context

1
2
3
4
5
6
7
8
9
10

error_context:
  prompt_file: ".github/prompts/phase-3/02-code-synthesis.prompt.md"
  error_log: |
    TypeError: Cannot read property 'id' of undefined
    at UserService.getUser (user.service.ts:42)
  generated_code: |
    const user = await db.findOne(User, { where: { email } });
    return user.id;  // FAILS: user can be null
  test_file: "user.service.test.ts"
  commit_sha: "abc123"

5.2 Analysis Phase

The Groomer:

  1. Reads the prompt file
  2. Reads the error log
  3. Identifies the gap between instruction and outcome
  4. Classifies the required vector

5.3 Output: Proposed Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

mutation_proposal:
  vector: "SPECIALIZATION"
  analysis: |
    The prompt instructs to "query the database" but does not
    specify null-handling requirements. The model assumed the
    query always returns a result.
  proposed_change:
    type: "append_to_constraints"
    content: |
      - Always check for null/undefined before accessing properties
      - Use optional chaining (?.) or explicit null guards
  evolution_log_entry: |
    - [2025-12-22]: NullPointerException on db.findOne result.
      FIX: Always null-check query results before property access.
  confidence: 0.92

6. The Semantic Economist Overlay

The Groomer integrates with the Cognitive Economy Model to prevent constraint bloat.

6.1 Before Adding Constraint

1
2
3
4
5
6
7
8
9
10
11
12
13
14

def propose_mutation(groomer: SemanticGroomer, prompt: PromptFile, error: ErrorContext):
    mutation = groomer.analyze(error)

    # Check budget
    if prompt.constraint_count >= BUDGET:
        # Find lowest value constraint
        weakest = min(prompt.constraints, key=lambda c: c.value())

        if mutation.expected_value > weakest.value:
            mutation.include_removal(weakest)
        else:
            return RejectionResult("Low-value mutation; not worth budget")

    return mutation

6.2 Market Rules Prompt Extension

1
2
3
4
5
6
7
8
9
10
11
12

# THE MARKET RULES (SEMANTIC ECONOMIST)
1. **Scarcity:** You have a budget of 20 constraints.
2. **Opportunity Cost:** To add a new constraint, prove it provides
   more value than the weakest existing constraint.
3. **Creative Destruction:** If a constraint is older than 10 cycles
   and hasn't prevented an error recently, DELETE IT.

# INSTRUCTION
Review the proposed update.
- If it is a "Black Swan" event (rare, catastrophic), add it.
- If it is "Noise" (minor style preference), reject it.
- If the budget is full, propose a "Swap" (Sell low, Buy high).

7. API Contract

7.1 Analyze Error

1

POST /groomer/analyze

Request:

1
2
3
4
5
6

{
  "prompt_path": ".github/prompts/phase-3/02-code-synthesis.prompt.md",
  "error_log": "TypeError: Cannot read property 'id' of undefined...",
  "generated_code_path": "src/services/user.service.ts",
  "test_file_path": "src/services/user.service.test.ts"
}

Response:

1
2
3
4
5
6
7

{
  "analysis_id": "uuid",
  "vector": "SPECIALIZATION",
  "confidence": 0.92,
  "proposed_diff": "--- a/.github/prompts/phase-3/02-code-synthesis.prompt.md\n+++ b/...",
  "evolution_entry": "- [2025-12-22]: NullPointer on db result. FIX: Null-check queries."
}

7.2 Apply Mutation

1

POST /groomer/apply/{analysis_id}

Request:

1
2
3
4

{
  "approval_type": "HUMAN" | "AUTO",
  "approver": "user@example.com"
}

7.3 Consolidate Prompt

1

POST /groomer/consolidate/{prompt_path}

Triggers rewrite of instructions when Evolution Log exceeds threshold.

8. Integration with CI/CD

8.1 GitHub Actions Workflow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

name: Prompt Evolution (Auto-Grooming)

on:
  workflow_run:
    workflows: ["CI Pipeline"]
    types: [completed]

jobs:
  groom:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch Error Logs
        run: gh run view ${{ github.event.workflow_run.id }} --log-failed > error.log

      - name: Invoke Groomer
        uses: sea-forge/groomer-action@v1
        with:
          error_log_path: error.log
          auto_apply: false  # Require human review

      - name: Create PR with Prompt Update
        uses: peter-evans/create-pull-request@v6
        with:
          title: "chore(prompts): auto-groom after CI failure"
          branch: auto-groom/${{ github.run_id }}