groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P1P2/reflection-code-patterns.md

@@ -1,1205 +0,0 @@
-# AI Agent Reflection - Practical Code Patterns
-
-This document provides copy-paste-ready patterns for implementing reflection in TypeScript/JavaScript agents.
-
-## Pattern 1: Simple Reflection Loop (Minimal)
-
-**Use Case**: Basic validation + single reflection pass
-**Lines of Code**: ~30
-**Tokens per attempt**: ~200-400
-
-```typescript
-async function simpleReflection(task: string): Promise<string> {
-  // Generate
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [{ role: "user", content: task }],
-  });
-  const output = response.content[0].text || "";
-
-  // Quick validation
-  if (output.length < 50) {
-    // Reflect and retry
-    const improved = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: `${task}\n\nYour previous response was too short. Provide a more detailed, comprehensive answer.`,
-        },
-      ],
-    });
-    return improved.content[0].text || output;
-  }
-
-  return output;
-}
-```
-
----
-
-## Pattern 2: Multi-Attempt Loop with History
-
-**Use Case**: Complex tasks needing intelligent retry
-**Lines of Code**: ~50
-**Tokens per attempt**: ~300-600
-
-```typescript
-interface AttemptRecord {
-  number: number;
-  output: string;
-  error: string | null;
-  timestamp: Date;
-}
-
-async function multiAttemptReflection(
-  task: string,
-  maxAttempts: number = 3
-): Promise<string> {
-  const attempts: AttemptRecord[] = [];
-
-  for (let i = 1; i <= maxAttempts; i++) {
-    const historyContext =
-      attempts.length > 0
-        ? `\n\nPrevious attempts:\n${attempts
-            .map((a) => `Attempt ${a.number}: ${a.error || "completed"}`)
-            .join("\n")}\n`
-        : "";
-
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: `${task}${historyContext}`,
-        },
-      ],
-    });
-
-    const output = response.content[0].text || "";
-    const validation = validateOutput(output);
-
-    if (validation.isValid) {
-      return output;
-    }
-
-    attempts.push({
-      number: i,
-      output,
-      error: validation.errors[0],
-      timestamp: new Date(),
-    });
-
-    // Request reflection if not on last attempt
-    if (i < maxAttempts) {
-      const reflection = await client.messages.create({
-        model: "claude-opus-4.5",
-        max_tokens: 300,
-        messages: [
-          {
-            role: "user",
-            content: `Task: ${task}\n\nYour attempt failed: ${validation.errors[0]}\n\nWhat should you try differently?`,
-          },
-        ],
-      });
-      console.log("Reflection:", reflection.content[0].text);
-    }
-  }
-
-  throw new Error(
-    `Failed after ${maxAttempts} attempts. Last error: ${
-      attempts[attempts.length - 1].error
-    }`
-  );
-}
-
-function validateOutput(output: string): {
-  isValid: boolean;
-  errors: string[];
-} {
-  const errors: string[] = [];
-  if (output.length < 20) errors.push("Output too short");
-  if (!output.includes(" ")) errors.push("No proper sentences");
-  return { isValid: errors.length === 0, errors };
-}
-```
-
----
-
-## Pattern 3: Error-Triggered Reflection
-
-**Use Case**: Reflection only on detected failures
-**Lines of Code**: ~60
-**Tokens per attempt**: ~400-800
-
-```typescript
-interface ReflectionContext {
-  originalInput: string;
-  failedOutput: string;
-  errorType: "validation" | "execution" | "logic";
-  errorMessage: string;
-}
-
-async function errorTriggeredReflection(
-  task: string,
-  executeTask: (input: string) => Promise<{ success: boolean; output: string; error?: string }>
-): Promise<string> {
-  let attempts = 0;
-  const maxAttempts = 3;
-
-  while (attempts < maxAttempts) {
-    attempts++;
-
-    // Generate solution
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [{ role: "user", content: task }],
-    });
-    const solution = response.content[0].text || "";
-
-    // Try to execute
-    const execution = await executeTask(solution);
-
-    if (execution.success) {
-      return solution;
-    }
-
-    // Build reflection context
-    const context: ReflectionContext = {
-      originalInput: task,
-      failedOutput: solution,
-      errorType: detectErrorType(execution.error),
-      errorMessage: execution.error || "Unknown error",
-    };
-
-    // Reflect on error
-    if (attempts < maxAttempts) {
-      const reflectionPrompt = buildReflectionPrompt(context);
-      const reflectionResponse = await client.messages.create({
-        model: "claude-opus-4.5",
-        max_tokens: 400,
-        messages: [{ role: "user", content: reflectionPrompt }],
-      });
-      const reflection = reflectionResponse.content[0].text || "";
-      console.log(`Attempt ${attempts} - Reflection:\n${reflection}\n`);
-
-      // Update task with reflection
-      task = `${context.originalInput}\n\nPrevious approach didn't work because: ${context.errorMessage}\n\nReflection: ${reflection}\n\nTry again with a different strategy.`;
-    }
-  }
-
-  throw new Error(
-    `Failed after ${maxAttempts} attempts on task: ${task.substring(0, 100)}`
-  );
-}
-
-function detectErrorType(
-  error: string | undefined
-): "validation" | "execution" | "logic" {
-  if (!error) return "logic";
-  if (error.includes("TypeError") || error.includes("SyntaxError"))
-    return "execution";
-  if (error.includes("assert") || error.includes("expect")) return "validation";
-  return "logic";
-}
-
-function buildReflectionPrompt(context: ReflectionContext): string {
-  return `Your solution failed with this error:
-
-ERROR TYPE: ${context.errorType}
-ERROR MESSAGE: ${context.errorMessage}
-
-Your attempted solution:
-${context.failedOutput}
-
-Analyze:
-1. Why did this approach fail?
-2. What's a fundamentally different approach?
-3. What assumption was wrong?
-
-Provide a new strategy to solve: ${context.originalInput}`;
-}
-```
-
----
-
-## Pattern 4: Instruction-Following Validation
-
-**Use Case**: Ensuring outputs meet explicit criteria
-**Lines of Code**: ~80
-**Tokens per attempt**: ~400-700
-
-```typescript
-interface ValidationRule {
-  name: string;
-  description: string;
-  validate: (output: string) => boolean;
-}
-
-interface ValidatedOutput {
-  output: string;
-  passedRules: string[];
-  failedRules: string[];
-}
-
-async function validateWithReflection(
-  task: string,
-  rules: ValidationRule[],
-  maxAttempts: number = 3
-): Promise<string> {
-  let output = "";
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    // Generate
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: buildGenerationPrompt(
-            task,
-            rules,
-            attempt > 1
-          ),
-        },
-      ],
-    });
-    output = response.content[0].text || "";
-
-    // Validate
-    const validation = validateOutput(output, rules);
-    console.log(`Attempt ${attempt}: ${validation.passedRules.length}/${rules.length} rules passed`);
-
-    if (validation.failedRules.length === 0) {
-      return output;
-    }
-
-    // Reflect if not last attempt
-    if (attempt < maxAttempts) {
-      const reflection = await client.messages.create({
-        model: "claude-opus-4.5",
-        max_tokens: 400,
-        messages: [
-          {
-            role: "user",
-            content: buildReflectionPromptForValidation(
-              task,
-              output,
-              validation.failedRules,
-              rules
-            ),
-          },
-        ],
-      });
-      console.log("Reflection:", reflection.content[0].text);
-    }
-  }
-
-  throw new Error(
-    `Validation failed after ${maxAttempts} attempts. ` +
-    `Failed rules: ${failedRules.join(", ")}`
-  );
-}
-
-function buildGenerationPrompt(
-  task: string,
-  rules: ValidationRule[],
-  includeReminder: boolean = false
-): string {
-  const rulesText = rules
-    .map((r) => `- ${r.name}: ${r.description}`)
-    .join("\n");
-
-  const reminderText = includeReminder
-    ? "\n\nREMINDER: Your previous response violated some of these rules. This time, ensure ALL rules are satisfied."
-    : "";
-
-  return `Task: ${task}
-
-Your response MUST satisfy these rules:
-${rulesText}${reminderText}`;
-}
-
-function validateOutput(
-  output: string,
-  rules: ValidationRule[]
-): ValidatedOutput {
-  const passedRules: string[] = [];
-  const failedRules: string[] = [];
-
-  for (const rule of rules) {
-    if (rule.validate(output)) {
-      passedRules.push(rule.name);
-    } else {
-      failedRules.push(rule.name);
-    }
-  }
-
-  return { output, passedRules, failedRules };
-}
-
-function buildReflectionPromptForValidation(
-  task: string,
-  output: string,
-  failedRules: string[],
-  allRules: ValidationRule[]
-): string {
-  const failedRulesDetails = allRules
-    .filter((r) => failedRules.includes(r.name))
-    .map((r) => `- ${r.name}: ${r.description}`)
-    .join("\n");
-
-  return `Task: ${task}
-
-Your response violated these rules:
-${failedRulesDetails}
-
-Your response was:
-${output}
-
-What specific changes would make your response satisfy all rules?`;
-}
-
-// Example usage
-const rules: ValidationRule[] = [
-  {
-    name: "proper_grammar",
-    description: "Response uses proper grammar and punctuation",
-    validate: (output) => output.includes(".") || output.includes("?"),
-  },
-  {
-    name: "min_length",
-    description: "Response is at least 100 characters",
-    validate: (output) => output.length >= 100,
-  },
-  {
-    name: "structured_format",
-    description: "Response uses clear formatting with sections",
-    validate: (output) => output.includes("\n") && output.split("\n").length >= 3,
-  },
-];
-
-// const result = await validateWithReflection(
-//   "Write about the benefits of reflection in AI",
-//   rules,
-//   3
-// );
-```
-
----
-
-## Pattern 5: Confidence-Based Reflection
-
-**Use Case**: Reflect only when model is uncertain
-**Lines of Code**: ~70
-**Tokens per attempt**: ~500-1000
-
-```typescript
-interface ConfidenceAssessment {
-  output: string;
-  confidence: number; // 0-1
-  uncertaintyAreas: string[];
-  suggestedAlternatives: string[];
-}
-
-async function confidenceBasedReflection(
-  task: string,
-  confidenceThreshold: number = 0.75
-): Promise<string> {
-  // First pass: generate and assess confidence
-  const assessment = await generateWithConfidence(task);
-
-  console.log(`Initial confidence: ${(assessment.confidence * 100).toFixed(0)}%`);
-  console.log(`Uncertainty areas: ${assessment.uncertaintyAreas.join(", ")}`);
-
-  // If confident enough, return immediately
-  if (assessment.confidence >= confidenceThreshold) {
-    console.log("Output meets confidence threshold, returning without reflection");
-    return assessment.output;
-  }
-
-  // If not confident, reflect and improve
-  console.log("Confidence below threshold, triggering reflection...");
-  const improved = await reflectOnLowConfidence(
-    task,
-    assessment
-  );
-
-  return improved;
-}
-
-async function generateWithConfidence(
-  task: string
-): Promise<ConfidenceAssessment> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1200,
-    messages: [
-      {
-        role: "user",
-        content: `${task}
-
-After providing your response, assess your own confidence by providing a JSON block:
-{
-  "confidence": <0.0 to 1.0>,
-  "uncertaintyAreas": ["area1", "area2"],
-  "suggestedAlternatives": ["alternative1", "alternative2"]
-}
-
-Only provide JSON for the assessment, nothing else after it.`,
-      },
-    ],
-  });
-
-  const text = response.content[0].text || "";
-  const jsonMatch = text.match(/\{[\s\S]*\}$/);
-
-  if (!jsonMatch) {
-    return {
-      output: text,
-      confidence: 0.5,
-      uncertaintyAreas: [],
-      suggestedAlternatives: [],
-    };
-  }
-
-  const assessment = JSON.parse(jsonMatch[0]);
-  return {
-    output: text.substring(0, text.lastIndexOf("{")),
-    confidence: assessment.confidence,
-    uncertaintyAreas: assessment.uncertaintyAreas || [],
-    suggestedAlternatives: assessment.suggestedAlternatives || [],
-  };
-}
-
-async function reflectOnLowConfidence(
-  task: string,
-  assessment: ConfidenceAssessment
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [
-      {
-        role: "user",
-        content: `Original task: ${task}
-
-Your previous response (confidence: ${(assessment.confidence * 100).toFixed(0)}%):
-${assessment.output}
-
-You identified these uncertainty areas:
-${assessment.uncertaintyAreas.map((a) => `- ${a}`).join("\n")}
-
-You considered these alternatives:
-${assessment.suggestedAlternatives.map((a) => `- ${a}`).join("\n")}
-
-Given your identified uncertainties, provide an improved response that:
-1. Directly addresses the uncertainty areas
-2. Is more thorough and robust
-3. Includes more detail or evidence
-4. Considers the alternatives you mentioned
-
-Provide your improved response, then a brief confidence assessment (0-1).`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-```
-
----
-
-## Pattern 6: Tool-Feedback Reflection (Code)
-
-**Use Case**: Reflection based on test/lint results
-**Lines of Code**: ~90
-**Tokens per attempt**: ~600-1200
-
-```typescript
-interface CodeFeedback {
-  type: "syntax" | "lint" | "test" | "runtime";
-  message: string;
-  severity: "error" | "warning";
-}
-
-async function codeGenerationWithReflection(
-  requirement: string,
-  maxAttempts: number = 3
-): Promise<string> {
-  let code = "";
-  const feedback: CodeFeedback[] = [];
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    // Generate code
-    const response = await client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 2048,
-      messages: [
-        {
-          role: "user",
-          content: buildCodeGenerationPrompt(
-            requirement,
-            feedback,
-            attempt
-          ),
-        },
-      ],
-    });
-
-    code = extractCode(response.content[0].text || "");
-
-    // Get feedback
-    const newFeedback = await getCodeFeedback(code);
-
-    if (newFeedback.length === 0) {
-      console.log(`Code passed on attempt ${attempt}`);
-      return code;
-    }
-
-    feedback.push(...newFeedback);
-    console.log(
-      `Attempt ${attempt}: ${newFeedback.length} issues found`
-    );
-
-    // Request reflection if not last attempt
-    if (attempt < maxAttempts) {
-      const reflection = await client.messages.create({
-        model: "claude-opus-4.5",
-        max_tokens: 400,
-        messages: [
-          {
-            role: "user",
-            content: buildCodeReflectionPrompt(
-              requirement,
-              code,
-              newFeedback
-            ),
-          },
-        ],
-      });
-      console.log("Reflection:", reflection.content[0].text);
-    }
-  }
-
-  throw new Error(
-    `Code generation failed after ${maxAttempts} attempts with ${feedback.length} issues`
-  );
-}
-
-function buildCodeGenerationPrompt(
-  requirement: string,
-  previousFeedback: CodeFeedback[],
-  attempt: number
-): string {
-  const feedbackText =
-    previousFeedback.length > 0
-      ? `\n\nPrevious issues found:\n${previousFeedback
-          .map(
-            (f) =>
-              `[${f.severity.toUpperCase()}] ${f.type}: ${f.message}`
-          )
-          .join("\n")}\n\nFix these issues in your new response.`
-      : "";
-
-  return `Generate TypeScript/JavaScript code for:
-${requirement}${feedbackText}
-
-Requirements:
-- Use modern TypeScript (5.2+)
-- Include proper type annotations
-- Include error handling
-- Include comments for complex logic
-- Be production-ready`;
-}
-
-async function getCodeFeedback(code: string): Promise<CodeFeedback[]> {
-  const feedback: CodeFeedback[] = [];
-
-  // Syntax check
-  try {
-    // Basic syntax validation (would use ts-node or similar in real implementation)
-    eval(code);
-  } catch (e) {
-    feedback.push({
-      type: "syntax",
-      message: String(e),
-      severity: "error",
-    });
-  }
-
-  // Lint checks (would use eslint in real implementation)
-  if (!code.includes("://") && code.includes("http")) {
-    feedback.push({
-      type: "lint",
-      message: "URL should be quoted string",
-      severity: "warning",
-    });
-  }
-
-  // Complexity check
-  const lines = code.split("\n").length;
-  if (lines > 100) {
-    feedback.push({
-      type: "lint",
-      message: "Function is too long, consider breaking it up",
-      severity: "warning",
-    });
-  }
-
-  return feedback;
-}
-
-function buildCodeReflectionPrompt(
-  requirement: string,
-  code: string,
-  feedback: CodeFeedback[]
-): string {
-  return `Requirement: ${requirement}
-
-Your code had these issues:
-${feedback.map((f) => `[${f.severity.toUpperCase()}] ${f.type}: ${f.message}`).join("\n")}
-
-Current code:
-${code}
-
-What specific changes would address these issues? Focus on:
-1. The root cause of each issue
-2. How to fix it without breaking functionality`;
-}
-
-function extractCode(text: string): string {
-  // Extract code from markdown code blocks
-  const codeBlockMatch = text.match(/```(?:typescript|javascript)?\n([\s\S]*?)\n```/);
-  if (codeBlockMatch) {
-    return codeBlockMatch[1];
-  }
-  return text;
-}
-```
-
----
-
-## Pattern 7: Multi-Agent Reflection (Generator + Critic)
-
-**Use Case**: Higher quality through dialogue between agents
-**Lines of Code**: ~100
-**Tokens per attempt**: ~800-1600
-
-```typescript
-interface CritiqueResult {
-  isSatisfactory: boolean;
-  strengths: string[];
-  weaknesses: string[];
-  suggestions: string[];
-}
-
-class GeneratorCriticReflection {
-  private client: LLMClient;
-  private maxRounds: number;
-
-  constructor(client: LLMClient, maxRounds: number = 3) {
-    this.client = client;
-    this.maxRounds = maxRounds;
-  }
-
-  async generate(task: string): Promise<string> {
-    let output = await this.generatorPass(task);
-
-    for (let round = 1; round < this.maxRounds; round++) {
-      const critique = await this.criticPass(task, output);
-
-      if (critique.isSatisfactory) {
-        console.log(`✓ Critique satisfied on round ${round}`);
-        return output;
-      }
-
-      console.log(`Round ${round} critique:`, critique.weaknesses);
-      output = await this.generatorImprove(
-        task,
-        output,
-        critique
-      );
-    }
-
-    return output;
-  }
-
-  private async generatorPass(task: string): Promise<string> {
-    const response = await this.client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [{ role: "user", content: task }],
-    });
-    return response.content[0].text || "";
-  }
-
-  private async generatorImprove(
-    task: string,
-    previousOutput: string,
-    critique: CritiqueResult
-  ): Promise<string> {
-    const response = await this.client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 1024,
-      messages: [
-        {
-          role: "user",
-          content: `Task: ${task}
-
-Previous output:
-${previousOutput}
-
-Critique feedback:
-Weaknesses: ${critique.weaknesses.join("; ")}
-Suggestions: ${critique.suggestions.join("; ")}
-
-Provide an improved version that addresses all the feedback.`,
-        },
-      ],
-    });
-    return response.content[0].text || "";
-  }
-
-  private async criticPass(
-    task: string,
-    output: string
-  ): Promise<CritiqueResult> {
-    const response = await this.client.messages.create({
-      model: "claude-opus-4.5",
-      max_tokens: 600,
-      messages: [
-        {
-          role: "user",
-          content: `You are a critical reviewer.
-
-Task: ${task}
-
-Response to critique:
-${output}
-
-Provide a JSON critique:
-{
-  "isSatisfactory": boolean,
-  "strengths": ["strength1", "strength2"],
-  "weaknesses": ["weakness1", "weakness2"],
-  "suggestions": ["suggestion1", "suggestion2"]
-}
-
-Respond with ONLY the JSON object.`,
-        },
-      ],
-    });
-
-    const text = response.content[0].text || "{}";
-    try {
-      return JSON.parse(text);
-    } catch {
-      return {
-        isSatisfactory: true,
-        strengths: [],
-        weaknesses: [],
-        suggestions: [],
-      };
-    }
-  }
-}
-
-// Usage
-// const gc = new GeneratorCriticReflection(client, 3);
-// const result = await gc.generate("Write an essay on AI reflection");
-```
-
----
-
-## Pattern 8: State-Aware Reflection with History
-
-**Use Case**: Learning from previous attempts within workflow
-**Lines of Code**: ~110
-**Tokens per attempt**: ~700-1400
-
-```typescript
-interface ExecutionState {
-  taskId: string;
-  attempt: number;
-  previousAttempts: Array<{
-    output: string;
-    result: "success" | "failed";
-    reason: string;
-    timestamp: Date;
-  }>;
-  currentError: string | null;
-  succeededApproaches: string[];
-  failedApproaches: string[];
-}
-
-async function stateAwareReflection(
-  task: string,
-  state: ExecutionState,
-  maxAttempts: number = 3
-): Promise<string> {
-  while (state.attempt < maxAttempts) {
-    state.attempt++;
-
-    // Generate solution informed by history
-    const solution = await generateInformedSolution(
-      task,
-      state
-    );
-
-    // Try to execute
-    const result = await executeAndValidate(solution);
-
-    if (result.success) {
-      // Record success
-      state.previousAttempts.push({
-        output: solution,
-        result: "success",
-        reason: "Execution passed all checks",
-        timestamp: new Date(),
-      });
-      state.succeededApproaches.push(result.approachUsed);
-      return solution;
-    }
-
-    // Record failure
-    state.previousAttempts.push({
-      output: solution,
-      result: "failed",
-      reason: result.error,
-      timestamp: new Date(),
-    });
-    state.failedApproaches.push(result.approachUsed);
-    state.currentError = result.error;
-
-    // Reflect before next attempt
-    if (state.attempt < maxAttempts) {
-      const reflection = await reflectWithState(
-        task,
-        solution,
-        result.error,
-        state
-      );
-      console.log(`Attempt ${state.attempt} reflection:`, reflection);
-    }
-  }
-
-  throw new Error(
-    `Task failed after ${maxAttempts} attempts. ` +
-    `Last error: ${state.currentError}`
-  );
-}
-
-async function generateInformedSolution(
-  task: string,
-  state: ExecutionState
-): Promise<string> {
-  const historyContext = buildHistoryContext(state);
-
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [
-      {
-        role: "user",
-        content: `${task}${historyContext}`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-
-function buildHistoryContext(state: ExecutionState): string {
-  if (state.previousAttempts.length === 0) {
-    return "";
-  }
-
-  const succeeded =
-    state.succeededApproaches.length > 0
-      ? `\n\nApproaches that worked: ${state.succeededApproaches.join(", ")}`
-      : "";
-
-  const failed =
-    state.failedApproaches.length > 0
-      ? `\nApproaches that failed: ${state.failedApproaches.join(", ")}`
-      : "";
-
-  const recent = state.previousAttempts
-    .slice(-2)
-    .map(
-      (a) =>
-        `Attempt ${a.previousAttempts.length}: ${a.result} (${a.reason})`
-    )
-    .join("\n");
-
-  return `${succeeded}${failed}\n\nRecent attempts:\n${recent}\n\nFor this attempt, try a different approach from what failed before.`;
-}
-
-async function reflectWithState(
-  task: string,
-  solution: string,
-  error: string,
-  state: ExecutionState
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 400,
-    messages: [
-      {
-        role: "user",
-        content: `Task: ${task}
-
-Attempt ${state.attempt} failed with: ${error}
-
-Your attempted solution:
-${solution}
-
-What different approach should we try next?
-- What assumptions was this approach based on?
-- How could those assumptions be wrong?
-- What fundamentally different strategy exists?`,
-      },
-    ],
-  });
-
-  return response.content[0].text || "";
-}
-
-async function executeAndValidate(solution: string): Promise<{
-  success: boolean;
-  error: string;
-  approachUsed: string;
-}> {
-  // Mock implementation - would be actual execution
-  try {
-    // Execute solution (parse, validate, run, etc.)
-    return {
-      success: true,
-      error: "",
-      approachUsed: "web_search_approach",
-    };
-  } catch (e) {
-    return {
-      success: false,
-      error: String(e),
-      approachUsed: "web_search_approach",
-    };
-  }
-}
-```
-
----
-
-## Pattern 9: Low-Token Reflection (Budget-Conscious)
-
-**Use Case**: Reflection with minimal token overhead
-**Lines of Code**: ~40
-**Tokens per attempt**: ~150-300
-
-```typescript
-async function budgetConsciousReflection(
-  task: string,
-  tokenBudget: number = 1000
-): Promise<string> {
-  let tokensUsed = 0;
-  let output = "";
-
-  // Initial generation
-  const gen1 = await client.messages.create({
-    model: "claude-haiku-4.5", // Cheaper model
-    max_tokens: Math.min(500, tokenBudget - 200),
-    messages: [{ role: "user", content: task }],
-  });
-
-  output = gen1.content[0].text || "";
-  tokensUsed += gen1.usage?.input_tokens || 0;
-  tokensUsed += gen1.usage?.output_tokens || 0;
-
-  if (tokensUsed + 200 > tokenBudget) {
-    return output;
-  }
-
-  // Lightweight reflection
-  const reflection = await client.messages.create({
-    model: "claude-haiku-4.5",
-    max_tokens: Math.min(300, tokenBudget - tokensUsed - 100),
-    messages: [
-      {
-        role: "user",
-        content: `Review this response for errors (brief 1-2 sentence assessment):\n\n${output.substring(
-          0,
-          500
-        )}...`,
-      },
-    ],
-  });
-
-  tokensUsed +=
-    reflection.usage?.input_tokens || 0;
-  tokensUsed +=
-    reflection.usage?.output_tokens || 0;
-
-  // If still within budget and issues found, do one quick pass
-  const reflectionText = reflection.content[0].text || "";
-  if (
-    tokensUsed + 200 <= tokenBudget &&
-    reflectionText.toLowerCase().includes("error")
-  ) {
-    const fix = await client.messages.create({
-      model: "claude-haiku-4.5",
-      max_tokens: 300,
-      messages: [
-        {
-          role: "user",
-          content: `Issue: ${reflectionText}\n\nOriginal response: ${output}\n\nQuick fix:`,
-        },
-      ],
-    });
-
-    output = fix.content[0].text || output;
-  }
-
-  return output;
-}
-```
-
----
-
-## Pattern 10: Timeout-Safe Reflection
-
-**Use Case**: Reflection with guaranteed completion
-**Lines of Code**: ~60
-**Tokens per attempt**: Variable
-
-```typescript
-interface TimeoutAwareReflectionOptions {
-  initialTimeout: number; // ms for first attempt
-  maxTotalTime: number; // ms for entire reflection
-  reflectionTime: number; // ms budget per reflection
-}
-
-async function timeoutSafeReflection(
-  task: string,
-  options: TimeoutAwareReflectionOptions
-): Promise<string> {
-  const startTime = Date.now();
-  const deadline = startTime + options.maxTotalTime;
-  let output = "";
-
-  try {
-    // First attempt with time limit
-    output = await withTimeout(
-      generateResponse(task),
-      options.initialTimeout
-    );
-    return output;
-  } catch (e) {
-    // If generation fails, return error instead of reflecting
-    if (Date.now() > deadline) {
-      throw new Error("Timeout exceeded during generation");
-    }
-  }
-
-  // Reflection (only if time permits)
-  const timeRemaining = deadline - Date.now();
-  if (timeRemaining < 500) {
-    // Less than 500ms left, don't reflect
-    return output;
-  }
-
-  try {
-    const reflection = await withTimeout(
-      reflectOnOutput(task, output),
-      Math.min(options.reflectionTime, timeRemaining - 100)
-    );
-    return reflection;
-  } catch (e) {
-    // Reflection failed or timed out, return what we have
-    console.warn("Reflection timed out or failed, returning original output");
-    return output;
-  }
-}
-
-async function withTimeout<T>(
-  promise: Promise<T>,
-  timeoutMs: number
-): Promise<T> {
-  return Promise.race([
-    promise,
-    new Promise<T>((_, reject) =>
-      setTimeout(
-        () => reject(new Error(`Operation timed out after ${timeoutMs}ms`)),
-        timeoutMs
-      )
-    ),
-  ]);
-}
-
-async function generateResponse(task: string): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 1024,
-    messages: [{ role: "user", content: task }],
-  });
-  return response.content[0].text || "";
-}
-
-async function reflectOnOutput(
-  task: string,
-  output: string
-): Promise<string> {
-  const response = await client.messages.create({
-    model: "claude-opus-4.5",
-    max_tokens: 400,
-    messages: [
-      {
-        role: "user",
-        content: `Quickly review and improve:\n\nTask: ${task}\n\nResponse: ${output}`,
-      },
-    ],
-  });
-  return response.content[0].text || output;
-}
-```
-
----
-
-## Quick Reference: Pattern Selection
-
-| Pattern | Best For | Tokens/Attempt | Latency |
-|---------|----------|------------------|---------|
-| Simple (1) | Basic validation | 200-400 | +200ms |
-| Multi-Attempt (2) | Complex tasks | 300-600 | +400ms |
-| Error-Triggered (3) | Execution errors | 400-800 | +500ms |
-| IFE Validation (4) | Explicit rules | 400-700 | +400ms |
-| Confidence (5) | Uncertain output | 500-1000 | +600ms |
-| Tool-Feedback (6) | Code/tests | 600-1200 | +800ms |
-| Multi-Agent (7) | High quality | 800-1600 | +1000ms |
-| State-Aware (8) | Learning workflows | 700-1400 | +700ms |
-| Budget-Conscious (9) | Limited tokens | 150-300 | +200ms |
-| Timeout-Safe (10) | Time constraints | Variable | Guaranteed |
-
----
-
-## Implementation Checklist
-
-When implementing reflection patterns:
-
-- [ ] Define success criteria (not vague goals)
-- [ ] Set max retry limit (typically 3-5)
-- [ ] Capture error context before reflection
-- [ ] Implement exponential backoff for transient errors
-- [ ] Use state deduplication to detect loops
-- [ ] Include cost/token tracking
-- [ ] Log all attempts and reflections
-- [ ] Test with both success and failure paths
-- [ ] Monitor reflection effectiveness (did it help?)
-- [ ] Consider latency impact on user experience
-- [ ] Plan graceful degradation if reflection fails
-