Skip to content

BATCH_ERROR_SYSTEM.md

Latest commit

 

History

History
158 lines (122 loc) · 4.3 KB

BATCH_ERROR_SYSTEM.md

File metadata and controls

158 lines (122 loc) · 4.3 KB

Batch Error System

NEW in v2.0: Parse all build errors at once, fix in batches, reduce compile cycles.

The Problem

AI agents fix one error at a time while the compiler reports ALL errors. This wastes:

  • CPU cycles (recompiling after each single fix)
  • Time (waiting for build to complete repeatedly)
  • Context (AI loses track of related errors)

The Solution

  1. Run build ONCE and capture ALL errors
  2. Parse errors into categorized JSON/Markdown
  3. Fix multiple errors before recompiling
  4. Only rebuild after completing a category or fixing 5+ errors

Quick Start

# Run build and parse all errors
.\batch_error_system\parse_build_errors.ps1 -RunBuild

# Or use the batch file
.\batch_error_system\Parse-Build-Errors.bat

Output Files

File Purpose
.ralph/build_errors.json Structured JSON for automation
.ralph/build_errors.md Human-readable markdown table
.ralph/build_output_cache.txt Raw build output

Error Categories

Errors are automatically categorized and prioritized:

Priority Category Description Fix First?
1 missing_include Missing headers ✅ YES
2 duplicate_definition Multiple definitions ✅ YES
3 namespace_error Namespace issues ✅ YES
4 missing_symbol Undefined symbols May auto-resolve
5 type_mismatch Type conversion No
6 syntax_error Syntax issues No
7 template_error Template issues Complex
8 linker_error Linker issues Often symptom

MSVC Error Codes

Code Meaning Category
C1083 Cannot open include file missing_include
C2065 Undeclared identifier missing_symbol
C2084 Duplicate definition duplicate_definition
C2143 Syntax error syntax_error
C2440 Cannot convert type_mismatch
C2653 Not a class/namespace namespace_error
LNK2001 Unresolved external linker_error
LNK2019 Unresolved external symbol linker_error

Usage Workflow

For Orchestrator (Single Builder)

# 1. Run build and parse errors
.\parse_build_errors.ps1 -RunBuild

# 2. Read the error report
cat .ralph\build_errors.md

# 3. Route errors to appropriate fixer agents (see table below)

# 4. Wait for fix reports

# 5. Rebuild
.\parse_build_errors.ps1 -RunBuild

# 6. Repeat until clean

For Fixer Agents (No Building!)

## Fix Report
- File: <path>
- Line: <number>
- Error Code: <C2143, etc.>
- Fix Applied: <description>
- Status: FIXED

⚠️ FIXER AGENTS DO NOT RUN CMAKE OR COMPILE

Error-to-Agent Routing

Error Pattern Assigned To
bind_*.cpp, pybind11 debug-agent
physics/*.cpp, Bullet* agent5-physics
vr/*.cpp, OpenXR* agent4-vr
*.py syntax/import agent9-python
CMakeLists.txt agent1-build
All other C++ debug-agent

Root Cause Analysis

The parser identifies:

  • Root Causes: Errors that should be fixed first (often clears cascading errors)
  • Cascade Errors: Errors that may auto-resolve after root causes are fixed

Example: A missing include (C1083) often causes 10+ "undeclared identifier" (C2065) errors downstream.

JSON Schema

{
  "Timestamp": "2026-01-21T04:00:00Z",
  "TotalErrors": 42,
  "RootCauseCount": 8,
  "CascadeCount": 34,
  "ByCategory": {
    "missing_include": { "Count": 3, "ErrorIds": [1, 2, 3] },
    "missing_symbol": { "Count": 15, "ErrorIds": [...] }
  },
  "ByFile": {
    "Renderer.cpp": { "Count": 5, "ErrorIds": [1, 4, 7, 9, 12] }
  },
  "Errors": [
    {
      "Id": 1,
      "File": "C:\\path\\to\\file.cpp",
      "Line": 42,
      "Column": 10,
      "Code": "C2065",
      "Message": "'foo': undeclared identifier",
      "Category": "missing_symbol",
      "Fixed": false
    }
  ],
  "RootCauses": [...],
  "Cascades": [...],
  "FixPriority": ["missing_include", "duplicate_definition", ...]
}

Best Practices

  1. Fix by category - Complete all missing_include before moving on
  2. Fix root causes first - Check the RootCauses list
  3. Group by file - Fix all errors in one file together
  4. Minimum batch size - Fix at least 5 errors before recompiling
  5. Update progress - Mark errors as fixed in the markdown table