ralph

# Ralph Iterative measurement-driven improvement loop. Each cycle: measure → profile → find biggest contributor → mutate → re-measure → commit only if improvement exceeds noise. ## 0. Gather inputs Use `AskUserQuestion` to collect: 1. **What to improve** — target metric and direction 2. **How to measure** — command or method (research and propose one if user doesn't know) 3. **How many cycles** — default 20 4. **Constraints** — what must NOT change ## 1. Setup - Create a feature branch and **draft PR** early (load `forge-pr` skill for title/body). PR description includes a measurements table updated as cycles complete. - **Baseline**: measure at least 5 runs, report **median**. For time: distinguish cold (no cache) from hot (cached). Document methodology. - Create `docs/<target>-ralph-report.md` with baseline, methodology, optimization log table, and findings. - Seed `TaskCreate` list with N cycle tasks — emit all calls as parallel `tool_use` blocks in a single assistant turn so the seed is one model round-trip, not N. ## 2. The loop Each cycle: 1. **Profile** — break down the metric into components. Measure each independently. Don't guess. 2. **Classify** — categorize the biggest contributor (unnecessary dep, eager eval, redundant work, wrong abstraction, missing cache, structural overhead). 3. **Mutate** — single, targeted change addressing the biggest contributor. 4. **Re-measure** — same benchmark, same methodology. If improvement is within noise (<3% for time), don't commit — document in report only. 5. **Commit + push** — only if improvement exceeds noise. Include metrics in commit message. Push report file with each commit. ## 3. Wrap-up - **Final measurement** with same methodology as baseline — this is the number for the PR. - **Update PR description** with final before/after table, summary of changes, key findings. - **Complete report** with optimization log, dead ends ("Investigated but no improvement"), key findings, and cost breakdown. - **Run CI** to verify nothing is broken. ## Rules - **Facts over opinions.** Measure everything. Don't commit based on theory. - **One change per cycle.** Isolate variables. - **Only commit improvements.** Noise-level changes clutter history. - **Preserve behaviour.** All changes behaviour-preserving unless user explicitly allows otherwise. - **Document dead ends.** "X doesn't help" is valuable knowledge. - **Stop at diminishing returns.** 3 consecutive no-improvement cycles → tell user and stop. - **Keep the report.** The `.md` is a deliverable — useful for blog posts and future reference.