groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P1P2/reflection-integration-guide.md

@@ -1,834 +0,0 @@
-# Reflection Integration Guide for Groundswell Agent Framework
-
-This guide explains how to integrate reflection patterns into the Groundswell workflow orchestration engine.
-
-## Architecture Overview
-
-Groundswell's hierarchical workflow engine provides the perfect foundation for reflection:
-
-```
-Workflow
-├── Step 1 (with reflection capability)
-├── Step 2 (with reflection capability)
-└── Step 3 (with reflection capability)
-    └── Child Workflow
-        ├── Sub-Step 1 (with reflection capability)
-        └── Sub-Step 2 (with reflection capability)
-```
-
-Each step/task can have reflection configured independently, allowing fine-grained control over when and how reflection occurs.
-
-## Core Integration Points
-
-### 1. **Step-Level Reflection**
-
-Add reflection configuration to the `@Step` decorator:
-
-```typescript
-interface StepReflectionConfig {
-  enabled: boolean;
-  trigger: "always" | "on-error" | "low-confidence";
-  maxAttempts: number;
-  validationRules?: ValidationRule[];
-  confidenceThreshold?: number;
-}
-
-@Step({
-  name: "GenerateCode",
-  reflection: {
-    enabled: true,
-    trigger: "on-error",
-    maxAttempts: 3,
-    validationRules: [
-      { name: "syntax", validate: (output) => checkSyntax(output) },
-      { name: "hasTests", validate: (output) => output.includes("test") }
-    ]
-  }
-})
-async generateCode(requirement: string): Promise<string> {
-  // Implementation
-}
-```
-
-### 2. **Task-Level Reflection**
-
-Configure reflection at the task/workflow level:
-
-```typescript
-@Task({
-  name: "CodeReviewWorkflow",
-  reflection: {
-    enabled: true,
-    trigger: "on-error",
-    maxAttempts: 3,
-    stateCapture: true, // Capture state before/after
-    errorCategories: {
-      transient: { retries: 3, backoff: "exponential" },
-      logical: { retries: 2, backoff: "linear" },
-      invalid: { retries: 0, escalate: true }
-    }
-  }
-})
-async reviewCode() {
-  // Implementation
-}
-```
-
-### 3. **Workflow-Level Reflection**
-
-Configure reflection at the orchestration level:
-
-```typescript
-class TestCycleWorkflow {
-  reflection: WorkflowReflectionConfig = {
-    enabled: true,
-    trigger: "on-workflow-error",
-    maxRounds: 3,
-    evaluationCriteria: {
-      allTestsPassed: true,
-      coverageAbove: 85,
-      noBlockingIssues: true
-    },
-    multiAgentCritique: {
-      enabled: true,
-      models: ["claude-opus-4.5", "claude-opus-4.5"] // Generator + Critic
-    }
-  };
-
-  async execute() {
-    // Multi-level workflow with reflection
-  }
-}
-```
-
-## Implementation Patterns for Groundswell
-
-### Pattern 1: Automatic Retry with Error Reflection
-
-```typescript
-import { Step, Task, WorkflowContext } from "@groundswell/core";
-
-@Step({
-  name: "ExecuteWithReflection",
-  reflection: {
-    enabled: true,
-    trigger: "on-error",
-    maxAttempts: 3
-  }
-})
-async executeWithReflection(
-  ctx: WorkflowContext,
-  input: string
-): Promise<string> {
-  const state = {
-    attempt: 0,
-    lastError: null,
-    attempts: [] as Array<{ output: string; error: string | null }>
-  };
-
-  while (state.attempt < 3) {
-    state.attempt++;
-
-    try {
-      const output = await this.attemptExecution(input, state.attempts);
-
-      // Emit success event
-      ctx.emit({
-        type: "step:success",
-        step: "ExecuteWithReflection",
-        attempt: state.attempt,
-        output
-      });
-
-      return output;
-    } catch (error) {
-      state.lastError = error;
-      state.attempts.push({ output: "", error: String(error) });
-
-      // Emit error event for observability
-      ctx.emit({
-        type: "step:error",
-        step: "ExecuteWithReflection",
-        attempt: state.attempt,
-        error: String(error)
-      });
-
-      // Trigger reflection if not last attempt
-      if (state.attempt < 3) {
-        const reflection = await this.reflect(
-          input,
-          String(error),
-          state.attempts
-        );
-
-        ctx.emit({
-          type: "step:reflection",
-          step: "ExecuteWithReflection",
-          attempt: state.attempt,
-          reflection
-        });
-      }
-    }
-  }
-
-  throw new Error(
-    `Step failed after 3 attempts. Last error: ${state.lastError}`
-  );
-}
-
-private async attemptExecution(
-  input: string,
-  history: Array<{ output: string; error: string | null }>
-): Promise<string> {
-  const historyContext = history.length > 0
-    ? `Previous attempts failed with: ${history
-        .map((h) => h.error)
-        .join("; ")}`
-    : "";
-
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [
-      {
-        role: "user",
-        content: `${input}\n${historyContext}`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-
-private async reflect(
-  input: string,
-  error: string,
-  attempts: Array<{ output: string; error: string | null }>
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 400,
-    messages: [
-      {
-        role: "user",
-        content: `Task: ${input}
-
-Failed with: ${error}
-
-What should we try differently?`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-```
-
-### Pattern 2: Validation-Driven Reflection
-
-```typescript
-@Step({
-  name: "GenerateAndValidate",
-  reflection: {
-    enabled: true,
-    trigger: "on-validation-failure",
-    maxAttempts: 3,
-    validationRules: [
-      { name: "required_fields", validate: (output) => hasRequiredFields(output) },
-      { name: "type_safety", validate: (output) => isTypeValid(output) },
-      { name: "business_rules", validate: (output) => meetsBusinessRules(output) }
-    ]
-  }
-})
-async generateAndValidate(
-  ctx: WorkflowContext,
-  requirement: string
-): Promise<string> {
-  const validationRules = [
-    { name: "required_fields", validate: (output: string) => hasRequiredFields(output) },
-    { name: "type_safety", validate: (output: string) => isTypeValid(output) },
-    { name: "business_rules", validate: (output: string) => meetsBusinessRules(output) }
-  ];
-
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    const output = await this.generate(requirement);
-
-    const violations = this.validate(output, validationRules);
-
-    if (violations.length === 0) {
-      ctx.emit({
-        type: "step:validation-passed",
-        step: "GenerateAndValidate",
-        attempt
-      });
-      return output;
-    }
-
-    ctx.emit({
-      type: "step:validation-failed",
-      step: "GenerateAndValidate",
-      attempt,
-      violations: violations.map((v) => v.name)
-    });
-
-    if (attempt < 3) {
-      const reflection = await this.reflectOnViolations(
-        requirement,
-        output,
-        violations
-      );
-
-      ctx.emit({
-        type: "step:reflection",
-        step: "GenerateAndValidate",
-        attempt,
-        reflection,
-        violationCount: violations.length
-      });
-    }
-  }
-
-  throw new Error("Validation failed after 3 attempts");
-}
-
-private validate(
-  output: string,
-  rules: Array<{ name: string; validate: (output: string) => boolean }>
-): Array<{ name: string; description: string }> {
-  const violations = [];
-  for (const rule of rules) {
-    if (!rule.validate(output)) {
-      violations.push({
-        name: rule.name,
-        description: `Failed: ${rule.name}`
-      });
-    }
-  }
-  return violations;
-}
-
-private async reflectOnViolations(
-  requirement: string,
-  output: string,
-  violations: Array<{ name: string; description: string }>
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 400,
-    messages: [
-      {
-        role: "user",
-        content: `Requirement: ${requirement}
-
-Your output violated these rules:
-${violations.map((v) => `- ${v.description}`).join("\n")}
-
-Output: ${output}
-
-How would you fix these violations?`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-```
-
-### Pattern 3: Confidence-Based Reflection
-
-```typescript
-interface ConfidenceOutput {
-  content: string;
-  confidence: number;
-  uncertaintyAreas: string[];
-}
-
-@Step({
-  name: "HighConfidenceGeneration",
-  reflection: {
-    enabled: true,
-    trigger: "low-confidence",
-    confidenceThreshold: 0.75,
-    maxAttempts: 2
-  }
-})
-async highConfidenceGeneration(
-  ctx: WorkflowContext,
-  task: string
-): Promise<string> {
-  // First pass with confidence assessment
-  const firstPass = await this.generateWithConfidence(task);
-
-  ctx.emit({
-    type: "step:confidence-assessment",
-    step: "HighConfidenceGeneration",
-    confidence: firstPass.confidence,
-    uncertaintyAreas: firstPass.uncertaintyAreas
-  });
-
-  if (firstPass.confidence >= 0.75) {
-    return firstPass.content;
-  }
-
-  // Low confidence, reflect and improve
-  const improved = await this.reflectOnUncertainty(
-    task,
-    firstPass
-  );
-
-  ctx.emit({
-    type: "step:low-confidence-reflection",
-    step: "HighConfidenceGeneration",
-    initialConfidence: firstPass.confidence,
-    reflection: improved
-  });
-
-  return improved;
-}
-
-private async generateWithConfidence(task: string): Promise<ConfidenceOutput> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1200,
-    messages: [
-      {
-        role: "user",
-        content: `${task}
-
-Assess your own confidence (respond with JSON after your answer):
-{"confidence": 0-1, "uncertaintyAreas": ["area1", "area2"]}`,
-      },
-    ],
-  });
-
-  const text = response.content[0].text || "";
-  const jsonMatch = text.match(/\{[\s\S]*\}$/);
-
-  if (jsonMatch) {
-    const meta = JSON.parse(jsonMatch[0]);
-    return {
-      content: text.substring(0, text.lastIndexOf("{")),
-      confidence: meta.confidence,
-      uncertaintyAreas: meta.uncertaintyAreas || []
-    };
-  }
-
-  return {
-    content: text,
-    confidence: 0.5,
-    uncertaintyAreas: []
-  };
-}
-
-private async reflectOnUncertainty(
-  task: string,
-  output: ConfidenceOutput
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [
-      {
-        role: "user",
-        content: `Task: ${task}
-
-Your response (confidence: ${output.confidence}):
-${output.content}
-
-You identified uncertainty in: ${output.uncertaintyAreas.join(", ")}
-
-Provide an improved response that addresses these uncertainty areas with more detail and evidence.`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-```
-
-### Pattern 4: Multi-Agent Reflection in Workflow
-
-```typescript
-@Task({
-  name: "ReviewAndIterateWorkflow",
-  reflection: {
-    enabled: true,
-    multiAgentCritique: {
-      enabled: true,
-      generatorModel: "claude-opus-4.5",
-      criticModel: "claude-opus-4.5",
-      maxRounds: 3
-    }
-  }
-})
-class ReviewAndIterateWorkflow {
-  @Step()
-  async generateOutput(ctx: WorkflowContext, requirement: string): Promise<string> {
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [{ role: "user", content: requirement }],
-    });
-    return response.content[0].text || "";
-  }
-
-  @Step()
-  async criticReview(
-    ctx: WorkflowContext,
-    output: string,
-    requirement: string
-  ): Promise<{
-    isSatisfactory: boolean;
-    feedback: string;
-    suggestions: string[];
-  }> {
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 600,
-      messages: [
-        {
-          role: "user",
-          content: `Requirement: ${requirement}
-
-Response to review:
-${output}
-
-Provide JSON critique:
-{"isSatisfactory": boolean, "feedback": string, "suggestions": ["s1", "s2"]}`,
-        },
-      ],
-    });
-
-    const text = response.content[0].text || "{}";
-    return JSON.parse(text);
-  }
-
-  @Step()
-  async improveBasedOnCritique(
-    ctx: WorkflowContext,
-    originalOutput: string,
-    requirement: string,
-    critique: { feedback: string; suggestions: string[] }
-  ): Promise<string> {
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: `Requirement: ${requirement}
-
-Original: ${originalOutput}
-
-Critique: ${critique.feedback}
-
-Suggestions: ${critique.suggestions.join("; ")}
-
-Provide improved version.`,
-        },
-      ],
-    });
-
-    return response.content[0].text || "";
-  }
-
-  async execute(ctx: WorkflowContext, requirement: string): Promise<string> {
-    let output = await this.generateOutput(ctx, requirement);
-
-    for (let round = 1; round <= 3; round++) {
-      const critique = await this.criticReview(ctx, output, requirement);
-
-      ctx.emit({
-        type: "workflow:critique",
-        round,
-        isSatisfactory: critique.isSatisfactory,
-        feedback: critique.feedback
-      });
-
-      if (critique.isSatisfactory) {
-        return output;
-      }
-
-      output = await this.improveBasedOnCritique(
-        ctx,
-        output,
-        requirement,
-        critique
-      );
-    }
-
-    return output;
-  }
-}
-```
-
-## State Capture & Observability
-
-### State Capture Before Reflection
-
-```typescript
-interface ReflectionSnapshot {
-  timestamp: Date;
-  stepName: string;
-  attemptNumber: number;
-  input: any;
-  output: string;
-  error: Error | null;
-  validationViolations: string[];
-  executionTimeMs: number;
-}
-
-async function captureStateBeforeReflection(
-  ctx: WorkflowContext,
-  step: string,
-  attempt: number,
-  input: any,
-  output: string,
-  error: Error | null,
-  violations: string[],
-  executionTimeMs: number
-): Promise<void> {
-  const snapshot: ReflectionSnapshot = {
-    timestamp: new Date(),
-    stepName: step,
-    attemptNumber: attempt,
-    input,
-    output,
-    error,
-    validationViolations: violations,
-    executionTimeMs
-  };
-
-  // Store in context for downstream access
-  ctx.state.reflectionHistory = ctx.state.reflectionHistory || [];
-  ctx.state.reflectionHistory.push(snapshot);
-
-  // Emit event for observability
-  ctx.emit({
-    type: "reflection:state-captured",
-    snapshot
-  });
-}
-```
-
-### Event-Based Observability
-
-```typescript
-// In your workflow/step implementation
-ctx.on("step:error", (event) => {
-  console.log(`Step ${event.step} failed on attempt ${event.attempt}`);
-  console.log(`Error: ${event.error}`);
-});
-
-ctx.on("step:reflection", (event) => {
-  console.log(`Reflection triggered for ${event.step}`);
-  console.log(`Reflection content: ${event.reflection}`);
-});
-
-ctx.on("reflection:state-captured", (event) => {
-  console.log(`State captured for reflection at ${event.snapshot.timestamp}`);
-  console.log(`Violations: ${event.snapshot.validationViolations.join(", ")}`);
-});
-
-ctx.on("step:success", (event) => {
-  console.log(`Step ${event.step} succeeded on attempt ${event.attempt}`);
-});
-```
-
-## Configuration Best Practices
-
-### Development Configuration
-
-```typescript
-const devConfig = {
-  reflection: {
-    enabled: true,
-    verbose: true,
-    captureFullState: true,
-    maxAttempts: 5, // More attempts for testing
-    logAllAttempts: true,
-    saveReflectionHistory: true
-  }
-};
-```
-
-### Production Configuration
-
-```typescript
-const prodConfig = {
-  reflection: {
-    enabled: true,
-    verbose: false,
-    captureFullState: false,
-    maxAttempts: 3, // Fewer attempts, lower cost
-    logAllAttempts: false,
-    saveReflectionHistory: false, // Save only on error
-    confidenceThreshold: 0.8, // Higher threshold
-    maxTokensPerReflection: 300,
-    timeoutMs: 5000
-  }
-};
-```
-
-## Cost Optimization
-
-### Cost Calculation
-
-```
-Base Cost = Input Tokens + Output Tokens
-Reflection Cost = Base Cost * (Number of Attempts - 1)
-
-Example:
-- Initial: 500 input + 500 output = 1000 tokens
-- Reflection (2 retries): 1000 * 2 = 2000 tokens
-- Total: 3000 tokens = 3x cost
-
-Rule of thumb: Each reflection attempt multiplies cost by ~2x
-```
-
-### Strategies to Reduce Cost
-
-1. **Use cheaper models for reflection**:
-```typescript
-const response = await client.messages.create({
-  model: state.attempt === 1
-    ? "claude-opus-4.5"  // First attempt with capable model
-    : "claude-haiku-4.5", // Reflection with cheaper model
-  max_tokens: 1024,
-  messages
-});
-```
-
-2. **Limit reflection scope**:
-```typescript
-const response = await client.messages.create({
-  model: "claude-opus-4.5",
-  max_tokens: state.attempt === 1
-    ? 2048  // First attempt, more tokens
-    : 400,  // Reflection, fewer tokens
-  messages
-});
-```
-
-3. **Confidence-based triggering**:
-```typescript
-if (output.confidence > 0.85) {
-  return output; // Skip reflection if confident
-}
-```
-
-## Monitoring & Metrics
-
-### Key Metrics to Track
-
-```typescript
-interface ReflectionMetrics {
-  stepName: string;
-  totalAttempts: number;
-  successOnFirstAttempt: number; // % that succeed without reflection
-  reflectionEffectiveness: number; // % improved by reflection
-  averageReflectionTime: number; // ms
-  totalTokensSpent: number;
-  costMultiplier: number; // How much more expensive than baseline
-}
-
-function calculateMetrics(history: ReflectionSnapshot[]): ReflectionMetrics {
-  const total = history.length;
-  const successful = history.filter((h) => h.error === null).length;
-  const successPercent = successful === 0 ? 0 : 1;
-
-  return {
-    stepName: history[0]?.stepName || "unknown",
-    totalAttempts: total,
-    successOnFirstAttempt: history.filter((h) => h.attemptNumber === 1).length,
-    reflectionEffectiveness: successPercent,
-    averageReflectionTime: 0, // Calculated from execution times
-    totalTokensSpent: 0, // Calculated from usage
-    costMultiplier: total // More attempts = higher multiplier
-  };
-}
-```
-
-## Testing Reflection
-
-### Unit Test Pattern
-
-```typescript
-describe("Step with Reflection", () => {
-  it("should succeed on first attempt", async () => {
-    const output = await step.execute(ctx, "simple task");
-    expect(output).toBeDefined();
-    expect(ctx.getEventCount("step:error")).toBe(0);
-  });
-
-  it("should retry on error", async () => {
-    // Mock to fail first, succeed second
-    const attempts: number[] = [];
-    step.generate = jest.fn(async () => {
-      attempts.push(1);
-      if (attempts.length === 1) throw new Error("First attempt fails");
-      return "success";
-    });
-
-    const output = await step.executeWithReflection(ctx, "task");
-    expect(output).toBe("success");
-    expect(attempts.length).toBe(2);
-  });
-
-  it("should fail after max attempts", async () => {
-    step.generate = jest.fn(async () => {
-      throw new Error("Always fails");
-    });
-
-    await expect(step.executeWithReflection(ctx, "task")).rejects.toThrow();
-  });
-});
-```
-
-## Troubleshooting
-
-### Infinite Reflection Loops
-
-**Problem**: Reflection keeps suggesting same fix without making progress
-
-**Solution**:
-```typescript
-// Add state deduplication
-const previousOutputs = new Set();
-const output = await generate();
-
-if (previousOutputs.has(output)) {
-  throw new Error("Stuck in loop, breaking out");
-}
-previousOutputs.add(output);
-```
-
-### Excessive Token Usage
-
-**Problem**: Reflection consuming too many tokens
-
-**Solution**:
-```typescript
-// Cap tokens per step
-const maxTokensPerStep = 2000;
-const maxTokensPerAttempt = maxTokensPerStep / maxAttempts;
-
-messages.max_tokens = Math.min(
-  1024,
-  maxTokensPerAttempt - tokensSoFar
-);
-```
-
-### Reflection Not Helping
-
-**Problem**: Output quality not improving with reflection
-
-**Solution**:
-```typescript
-// Track effectiveness
-if (attempt > 1 && newOutput.quality <= previousOutput.quality) {
-  // Reflection didn't help, return original
-  return previousOutput;
-}
-```
-