Self-Healing Compilation With YAML Frontmatter In Ralph

by Editorial Team 56 views
Iklan Headers

Hey guys! Today, we're diving deep into a proposal to supercharge Ralph with some seriously cool self-healing capabilities. This involves auto-deriving state from YAML frontmatter and adding compilation checks that can automatically fix common issues. Let's get started!

The Problem: Manual State Tracking is a Pain

Currently, Ralph relies on manually maintained artifacts to keep track of its state. This includes:

  1. STATE.md: A file that's manually updated to reflect the current phase, plan position, and overall progress.
  2. Progress bars: These are scattered throughout ROADMAP.md and other locations, also requiring manual updates.
  3. No compilation verification: Ralph trusts that plans will always leave the project in a buildable state, which isn't always the case.
  4. Silent breakages: Plans can complete successfully, but the project might still be broken without anyone noticing immediately.

This manual approach leads to several problems:

  • Maintenance burden: Keeping STATE.md in sync with the actual state is tedious and time-consuming.
  • Drift: The tracked state can easily diverge from the actual state, leading to confusion and errors.
  • Undetected broken builds: Builds can break and go unnoticed until the next plan runs, causing delays and frustration.
  • Lack of self-healing: There's no mechanism to automatically fix issues when plans make incomplete updates.

Proposed Solution: Automate Everything!

To address these issues, we propose a solution that involves deriving state from YAML frontmatter, auto-updating progress bars, adding post-plan compilation verification, and implementing a self-healing fix agent.

1. Derive State from YAML Frontmatter: The Single Source of Truth

Instead of manually maintaining STATE.md, we can derive all state information directly from the YAML frontmatter in the plan files. Check it out:

Plan file with YAML frontmatter:

---
phase: 5.1
plan: 01
status: complete
completed_at: 2026-01-15T22:11:03Z
retry_count: 2
---

# Phase 5.1, Plan 01: Fix File Registration

<tasks>
...
</tasks>

With this approach, Ralph can read all plan files and derive the following information:

  • Current position: The last incomplete plan (or the first plan with status: in-progress).
  • Progress: The count of status: complete plans versus the total number of plans.
  • Phase completion: Whether all plans in a phase are marked as complete.
  • Retry history: The retry_count field in the frontmatter.

Benefits:

  • Single source of truth: The plan files themselves contain all the state information.
  • No manual STATE.md updates: Say goodbye to tedious manual updates!
  • ralph status just aggregates frontmatter data: The ralph status command simply aggregates the data from the frontmatter.
  • Git history shows exactly when each plan completed: Git history provides a clear record of when each plan was completed.

This approach simplifies state management and ensures that the tracked state is always up-to-date. It leverages Git history, so you can always track changes and understand the evolution of the project's state.

2. Auto-Update Progress Bars: No More Manual Tweaks

Manually updating progress bars is a drag. Let's automate it! Ralph should automatically update progress bars in ROADMAP.md based on the YAML frontmatter.

Before (manual):

## Phase 5.1: Fix AR Navigation
Status: ◐ In Progress
Plans: [████░░] 2/3 complete

After (auto-generated):

Ralph updates this section by:

  1. Reading all 05-01*.md plan files in the phase directory.
  2. Counting status: complete plans.
  3. Updating ROADMAP.md progress bars programmatically.

Command:

ralph sync  # Updates all progress bars in ROADMAP.md from plan frontmatter

This command can be run manually or automatically after every plan completion. Automating progress bar updates saves time and ensures that the roadmap always reflects the current state of the project. No more worrying if the progress bar is up-to-date!

3. Post-Plan Compilation Verification: Catch Breakage Early

To prevent broken builds from slipping through the cracks, Ralph should verify the project still builds after every plan completes.

Workflow:

[Plan execution completes]
  ↓
[Ralph: Mark plan complete in frontmatter]
  ↓
[Ralph: Run compilation check]
  ↓
[If build passes] → Continue to next plan
  ↓
[If build fails] → Launch fix agent

This workflow ensures that any build issues are detected immediately after a plan completes, allowing for quick remediation.

Configuration in .ralph/config.yaml:

compilation_check:
  enabled: true
  commands:
    - name: "Xcode build"
      command: |
        cd ar/AR && xcodebuild -scheme "AR (iOS)" \
          -destination 'platform=iOS Simulator,name=iPhone 17' \
          build
      timeout: 600
      
    - name: "Go tests"
      command: go test ./...
      timeout: 300
      
  # What to do on failure
  on_failure: auto-fix  # Options: auto-fix, stop, warn

This configuration allows you to define the compilation checks that Ralph should run, including the commands to execute and the timeout for each check. You can also specify what to do if a check fails, such as automatically launching a fix agent.

4. Self-Healing Fix Agent: Automatically Fix Common Issues

The most exciting part of this proposal is the self-healing fix agent. When a compilation check fails, Ralph automatically launches a fix agent to diagnose and fix the issue.

Fix agent workflow:

[Build failed after Plan 05-01 completion]
  ↓
[Ralph: Capture build error output]
  ↓
[Ralph: Launch Claude agent with context]
  - Last plan that completed (05-01-PLAN.md)
  - Build error output
  - Files modified in last plan (from git diff)
  ↓
[Claude agent: Diagnose and fix]
  - Read the plan that just completed
  - Analyze build errors
  - Identify missing updates (file registrations, imports, etc.)
  - Apply fixes
  - Verify build passes
  ↓
[Ralph: Append fix to plan's Progress section]
  ↓
[Ralph: Re-run compilation check]
  ↓
[If still failing] → Escalate to human (stop loop)
[If passing] → Continue to next plan

The fix agent uses a large language model (like Claude) to analyze the build error, identify the missing updates, and apply fixes. It then verifies that the build passes after applying the fixes.

Fix agent prompt includes:

  • "Plan 05-01 just completed but the build is now failing"
  • "Build error: [full compiler output]"
  • "Files modified in this plan: [git diff --name-only]"
  • "Your job: Fix the build by completing any missing updates"
  • "Common issues: file registration, missing imports, incorrect paths"

Append to plan's Progress section:

## Progress

### Run 1 (2026-01-15 22:11:03)
- ✅ Task 1: Move file to correct target
- ✅ Task 2: Verify build
- ✅ Plan marked complete

### Post-completion fix (2026-01-15 22:15:30)
- ⚠️ Build failed after plan completion
- Error: No such module 'SpatialStoryModels'
- Fix applied: Added missing import in SpatialStoriesExperienceView.swift
- ✅ Build now passing

This ensures that all fixes are logged in the plan's Progress section, providing a clear record of the changes that were made.

Implementation Phases: A Step-by-Step Approach

To implement this solution, we propose the following phases:

Phase 1: YAML Frontmatter State Tracking

  • Add frontmatter parsing to all Ralph commands.
  • Derive the current position from the plan file status fields.
  • Deprecate (but don't remove) STATE.md - make it read-only.

Phase 2: Auto-Update Progress Bars

  • Implement the ralph sync command.
  • Auto-run after plan completion.
  • Update ROADMAP.md progress bars programmatically.

Phase 3: Compilation Verification

  • Add compilation check configuration to .ralph/config.yaml.
  • Run checks after plan completion.
  • Report pass/fail clearly.

Phase 4: Self-Healing Fix Agent

  • Implement the auto-fix agent with context about the last plan.
  • Append fixes to the plan's Progress section.
  • Escalate to a human if the fix fails.

Benefits: A World of Goodness

This solution offers several key benefits:

  1. Less manual work: No more STATE.md updates or progress bar tweaks!
  2. Single source of truth: Plan files contain all the state information.
  3. Catch breakage early: Build failures are detected immediately after plan completion.
  4. Self-healing: Common mistakes are automatically fixed.
  5. Transparency: All fixes are logged in the plan's Progress section.
  6. Git-friendly: All state changes are in Git-tracked files.

Alternative Considered: Auto-Generate STATE.md?

We considered keeping STATE.md but auto-generating it. However, this adds an extra layer of complexity. Why not just read the state directly from the plan files?

Related Issues: Connecting the Dots

This proposal relates to the following issues:

  • Issue #13: Mandatory validation enforcement - compilation checks are a form of mandatory validation.
  • Issue #14: ralph list showing stale phases - YAML frontmatter would help identify active vs stale phases.

Migration Path: Bringing Existing Projects Onboard

For existing projects with STATE.md:

  1. The ralph migrate command reads STATE.md and backfills the YAML frontmatter into all plan files.
  2. STATE.md becomes read-only (Ralph warns if it's manually edited).
  3. Future versions can remove STATE.md entirely.

In summary, this proposal aims to significantly improve Ralph's state management and self-healing capabilities. By deriving state from YAML frontmatter, automating progress bar updates, adding compilation verification, and implementing a self-healing fix agent, we can reduce manual work, catch breakage early, and ensure that the project remains in a buildable state. Let me know what you think!