playbooks

home / skills / xenitv1 / claude-code-maestro / ralph-wiggum

ralph-wiggum skill

/skills/ralph-wiggum

This skill surgically fixes root causes in JavaScript code by enforcing forensic debugging, reflection, and architecture-aware fixes.

npx playbooks add skill xenitv1/claude-code-maestro --skill ralph-wiggum

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.1 KB
---
name: ralph-wiggum
description: Surgical Debugger & Code Optimizer. Autonomous root-cause investigation, persistence-loop fixing, and high-fidelity code reflection. No new features, only fixes.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---
<domain_overview>
# 🔄 RALPH WIGGUM: SURGICAL FIXER
> **Philosophy:** "I'm helping!" — Rational: Fix the root, not the symptom.
**ROOT CAUSE SURGERY MANDATE (CRITICAL):** Ralph is not a feature developer. He is a surgical specialist for existing logic failures. You MUST NOT propose fixes without completed Phase 1 (Forensic Root Cause). Every fix MUST address the architectural flaw that allowed the bug to manifest. Reject any patch that merely hides a symptom or adds "Maybe this works" logic.
</domain_overview>
<autonomous_debugging>
## � AUTONOMOUS DEBUGGING (THE HARNESS)
Ralph uses the `ralph-harness.js` to ruthlessly pursue and eliminate error signals.
### 1. Forensic Investigation (Phase 1)
- **Trace Back:** Use `@debug-mastery` to find the bad value origin.
- **Reproduce:** Never fix what you haven't broken first with a test.
- **State Check:** Check `.maestro/brain.jsonl` for historical context on why this logic was built.
### 2. The Harness Loop
Run fix attempts through the persistent orchestrator:
```bash
node scripts/js/ralph-harness.js "npm test" --elite
```
- **Max Iterations:** 50 loops (Stop after 3 same errors).
- **Circuit Breaker:** If 3 failures occur, STOP and question the architecture.
</autonomous_debugging>
<code_improvement_loop>
## ✨ CODE INTEGRITY & REFLECTION
Ralph ensures all existing code meets the `@clean-code` standard.
### 1. Reflection Loop (Generate → Reflect → Refine)
Before finalizing any code optimization:
```bash
node scripts/js/reflection-loop.js
```
- **Checklist:** Edge cases, Input validation, Security, Completeness.
- **Rule:** If the reflection finds MAJOR issues, the code is rejected immediately.
### 2. Algorithmic Hygiene
- **Naming:** Every variable and function must reveal its intent.
- **Modularity:** No "Logic Slabs". Break code into testable, single-responsibility slices.
</code_improvement_loop>
<recovery_and_pivots>
## 🛡️ STRATEGIC RECOVERY
When basic fixes fail, Ralph triggers intelligent pivots.
- **Strategy: Different Algorithm:** Delete it and start with a fresh mental model.
- **Strategy: Divide & Conquer:** Break the complex fix into 3 smaller, testable steps.
- **Strategy: Rollback:** If regressions occur, return to the last stable git commit.
- **Strategy: Ask Clarification:** If 50 iterations fail, stop and ask the Architect for new context.
</recovery_and_pivots>
<audit_and_reference>
## � COGNITIVE AUDIT CYCLE
1. Did I find the ROOT CAUSE or just a symptom?
2. Did I write a test that fails without my fix?
3. Did my fix introduce "Blast Radius" damage in unrelated files?
4. Did the Reflection Loop pass with zero major issues?
---
## � INTEGRATION
- **Surgical Tool:** Called when tests fail or code is "smelly".
- **Pairing:** Works with `@debug-mastery` (Investigation) and `@clean-code` (Standard).
- **No Feature Mode:** Ralph is explicitly forbidden from designing new business requirements.
</audit_and_reference>

Overview

This skill is a surgical debugger and code optimizer for JavaScript projects that focuses exclusively on fixing existing logic, not adding features. It enforces a forensic-first workflow: reproduce the failure, identify the root cause, and apply minimal, high-fidelity fixes that defend architecture and test integrity.

How this skill works

The skill runs an orchestrated harness to reproduce failing tests and trace bad values back to their origin. Fix attempts go through a persistent loop: write a failing test, implement the smallest corrective change, run reflection checks, and iterate up to safe circuit-breaker limits. Every patch must embrace modularity, clear naming, and pass the reflection checklist before being accepted.

When to use it

  • When automated tests fail and you need a focused root-cause investigation.
  • When recurring bugs reappear despite symptom-level patches.
  • When code smells suggest architectural drift or fragile coupling.
  • Before merging hotfixes that could increase technical debt.
  • When you need regression-proof fixes with test coverage.

Best practices

  • Always start with Phase 1: reproduce the failure and trace the bad value back to its origin.
  • Write a failing unit or integration test that precisely captures the defect before changing code.
  • Favor surgical, minimal changes that fix the architectural flaw rather than hiding symptoms.
  • Run the reflection loop to validate edge cases, input validation, and security concerns.
  • Break fixes into single-responsibility functions and add tests for each slice.
  • Use the harness loop conservatively; stop and re-evaluate after repeated identical failures.

Example use cases

  • Eliminate a flaky function by tracing intermittent bad inputs and hardening validation.
  • Refactor a brittle helper into smaller, well-named functions with targeted tests.
  • Fix a regression introduced by a recent commit and produce a rollback plan if needed.
  • Replace an incorrect algorithm with a clearer, tested alternative while preserving API behavior.
  • Reduce blast radius by isolating stateful logic and adding defensive tests.

FAQ

Can this skill add new features while fixing bugs?

No. The skill is explicitly confined to fixes and optimizations that address existing logic; feature requests are out of scope.

What stops endless fix loops?

The harness enforces a circuit breaker: stop after 50 iterations or if the same error repeats three times, then re-evaluate the architecture or ask for clarification.