Introduction
# 🧬 Ralph-Evolver
**Philosophy: Recursion + Emergence + First Principles**
## Signal Sources
Collects multi-dimensional context, not just code structure: - **Commit history** - Understand the "why" behind changes - **TODO/FIXME** - Distress signals in the code - **Error handling patterns** - Find fragile points - **Hotspot files** - Frequent changes = design problems
Each signal includes a **hypothesis prompt** to guide deeper analysis.
## First Principles
Each run doesn't execute a checklist, but asks: 1. What is the **essence** of this project? 2. What is it doing that it **shouldn't**? 3. What is it **missing** that it should have? 4. If you **started from scratch**, how would you build it?
## Meta-Reflection (v1.0.5)
When analyzing itself, evolver asks: - Is this a **surface fix** or **evolution-level** improvement? - What **pattern** exists in improvement history? - Will this change make evolver **better at finding problems**?
## Improvement Tracking
- Records description, insight, **level** (surface/evolution), and health metrics - **Pattern analysis**: counts surface/evolution ratio, finds recurring themes - Compares before/after effect trends (improved/degraded/unchanged)
## Usage
```bash node index.js . # Current directory (positional) node index.js /path/to/app # Specify path node index.js . --loop 5 # Run 5 cycles node index.js --task "fix auth" # Specific task node index.js --reset # Reset iteration state ```
## Recursion
The improver can improve itself. This is true recursion.
---
*"Form hypotheses, then verify. Think from first principles."*