Code Optimization Loop

Relevant source files

The following files were used as context for generating this wiki page:

• src/engine/optimizationLoop.ts
• src/engine/codeAnalyzer.ts
• src/engine/codeModifier.ts
• src/engine/reportGenerator.ts
• plan.md
• README.md

The Code Optimization Loop is the central orchestrator for SynthCrowd's "test-fix-verify" cycle. It automates the process of testing a website against a synthetic population, identifying specific UX friction points through AI-driven analysis of agent failures, applying targeted code modifications to resolve those points, and rerunning the tests to verify improvements.

The system aims to iterate until a predefined conversion threshold is reached (e.g., 75%) or a maximum number of iterations is exhausted. This closed-loop architecture ensures that every code change is backed by synthetic user evidence and verified by subsequent testing to prevent regressions.
Sources: plan.md:14-23, src/engine/optimizationLoop.ts:153-158

Architecture and Workflow

The optimization loop follows a multi-stage pipeline that integrates persona generation, parallel agent execution, failure analysis, and automated code modification.

High-Level Flow

The following diagram illustrates the iterative nature of the optimization process:

This flowchart shows the lifecycle of a single optimization session, highlighting the decision points for threshold checks and the manual/automatic approval gate.
Sources: plan.md:25-78, src/engine/optimizationLoop.ts:133-286

Component Breakdown

1. Execution Orchestrator

The runOptimizationLoop function manages the session state, iteration counting, and the hand-off between sub-modules. It maintains the sessionId to ensure the same population of personas is used throughout different iterations, which is critical for measuring the direct impact of code changes.
Sources: src/engine/optimizationLoop.ts:133-145, plan.md:73-78

2. Failure Analysis (codeAnalyzer.ts)

When agents fail to convert, the analyzeFailures function processes their narratives and specific friction points. It uses the claude-sonnet-4-20250514 model to compare the failure reasons against the actual source code of the website.

• Logic: It groups friction points and identifies which personas were affected by each.
• Output: A list of ProposedChange objects containing exact string replacements.
• Validation: The analyzer validates that the "original" string exists in the source file before proposing the change.
  Sources: src/engine/codeAnalyzer.ts:57-115, src/engine/codeAnalyzer.ts:122-136

3. Code Modification (codeModifier.ts)

The modification engine applies the validated proposals to the local filesystem.

• Rollback Safety: Before applying any change, it executes a git commit to create a recovery point.
• Verification: After writing the new content, it attempts to fetch the siteUrl. If the site fails to load or returns an invalid status, it executes a git revert to restore the last known good state.
  Sources: src/engine/codeModifier.ts:17-31, src/engine/codeModifier.ts:80-95

Key Data Structures

Optimization Options

Parameter	Type	Description
threshold	number	The target conversion rate (0-1) to stop the loop.
maxIterations	number	Maximum number of test-fix cycles allowed.
autoMode	boolean	If true, applies changes without the onAwaitingApproval gate.
sitePath	string	Local directory containing the website source code.
sessionId	string	UUID for tracking personas across iterations via MongoDB.
Sources: src/engine/optimizationLoop.ts:31-46

Proposed Change Schema

{
  "file": "filename.html",
  "description": "Short description of the change",
  "original": "exact string from source",
  "replacement": "new string",
  "reasoning": "Why this fixes the friction",
  "targetFriction": "Friction point ID"
}

Sources: src/engine/codeAnalyzer.ts:6-13

Iteration Trajectory

The system tracks the "Trajectory" of a session, which is a string representation of conversion rates over time.

Example Trajectory: 40% → 58% → 78% ✓

This is calculated by collecting the conversion results of each parallel agent run within the iterations array of the OptimizationResult.
Sources: src/engine/optimizationLoop.ts:58-64, src/engine/optimizationLoop.ts:300-303, plan.md:118-120

Implementation Constraints

• Minimal Changes: The CODE_ANALYSIS_SYSTEM_PROMPT instructs the AI to be conservative, prioritizing copy, styling, and layout over restructuring or adding dependencies.
• File Filtering: The loop only reads specific file extensions (.tsx, .ts, .jsx, .js, .css, .html) and skips large files (>50KB) or dependency directories like node_modules.
• Verification Timeout: Site load verification uses a strict 10-second timeout to prevent the loop from hanging on broken builds.
  Sources: src/engine/codeAnalyzer.ts:21-28, src/engine/optimizationLoop.ts:66-72, src/engine/codeModifier.ts:35

Summary

The Code Optimization Loop transforms synthetic user feedback into tangible site improvements. By combining automated failure analysis with git-backed safe code modifications, it allows for rapid, data-driven UX iteration. The process ensures that even if a "fix" breaks the site, the system automatically reverts to a stable state, maintaining the integrity of the target application throughout the optimization lifecycle.