Il pattern "Ralph Wiggum" sta diventando l'infrastruttura di default per chi vuole far lavorare un coding agent oltre la singola sessione. Il nome, derivato dal personaggio dei Simpson noto per la sua persistenza ingenua, cattura l'essenza della tecnica: un loop infinito che alimenta ripetutamente lo stesso prompt a un agente AI, dove il progresso non persiste nella context window del modello ma vive nei file e nella storia git.

Esistono oggi due implementazioni principali: la versione originale di Ryan Carson (snarktank/ralph), uno script bash essenziale che orchestra Amp, e Ralph TUI, un orchestratore completo con interfaccia terminale, plugin per diversi agenti e tracker, e gestione delle sessioni. Entrambi derivano dall'intuizione di Geoffrey Huntley, che sintetizza il principio così: "La tecnica è deterministicamente cattiva in un mondo indeterministico. È meglio fallire prevedibilmente che avere successo imprevedibilmente."

Il ciclo di esecuzione: cosa succede concretamente

Ralph opera in cinque fasi che si ripetono fino al completamento o al raggiungimento di un limite di iterazioni.

Selezione del task. L'orchestratore interroga il tracker (un file prd.json, Beads, o altri backend) e seleziona il task con priorità più alta che non ha dipendenze bloccanti. Il task deve avere passes: false per essere candidato. Questa selezione è deterministica: nessuna interpretazione semantica, solo stato e dipendenze.

Costruzione del prompt. Il task viene trasformato in un prompt tramite template Handlebars. Qui avviene l'iniezione di contesto: acceptance criteria, quality gate, dipendenze completate, note dalle iterazioni precedenti. Il template è personalizzabile, e questa è la leva principale per adattare Ralph al proprio stack.

Esecuzione dell'agente. Ralph spawna un processo fresh dell'agente scelto (Claude Code, OpenCode, Amp) con il prompt costruito. L'output viene streamato in tempo reale. Il punto critico: ogni iterazione è un'istanza fresh con contesto pulito. La memoria tra iterazioni persiste solo via git history, progress.txt e prd.json.

Rilevamento del completamento. L'agente segnala che ha finito emettendo un token specifico: <promise>COMPLETE</promise>. Quando l'agente produce questo output, Ralph TUI riconosce che il task è completato e passa al successivo. Questo rilevamento token-based abilita l'operazione completamente autonoma. Non c'è comprensione semantica: è un protocollo, un segnale deterministico.

Transizione. Il task viene marcato come completato nel tracker, lo stato della sessione viene salvato, e il ciclo ricomincia.

Anatomia del PRD: specifica come contratto

Il PRD nel mondo Ralph non è documentazione, è input per un compilatore. La struttura deve essere parsabile: user story con ID strutturati (US-001, US-002...), acceptance criteria come checklist verificabili, quality gate come comandi shell.

La fase di convert in Ralph TUI fa qualcosa di importante: estrae i quality gate dalla sezione dedicata e li appende agli acceptance criteria di ogni singola story. Questo significa che ogni task porta con sé i propri controlli di qualità: non esiste un "test finale" a progetto concluso, la qualità è atomica, per-task, non negoziabile.

Esempio di quality gate da includere nel PRD:

## Quality Gates

Questi comandi devono passare per ogni user story:
- `bun run typecheck` - Type checking
- `bun run lint` - Linting
- `bun run test` - Test suite

Setup operativo: dalla teoria all'esecuzione

Installazione di Ralph TUI:

bun install -g ralph-tui
cd your-project
ralph-tui setup

Il wizard interattivo rileva gli agenti installati, crea la configurazione in .ralph-tui/config.toml, e installa le skill per la creazione di PRD.

Creazione del PRD:

ralph-tui create-prd --chat

L'AI ti guida attraverso domande su obiettivi, scope, utenti target, quality gate. Output: un file markdown strutturato in ./tasks/prd-<feature>.md.

Conversione in task eseguibili:

ralph-tui convert --to json ./tasks/prd-my-feature.md

Produce prd.json con user story pronte per l'esecuzione autonoma.

Avvio del loop:

ralph-tui run --prd ./prd.json

Ralph seleziona il primo task, costruisce il prompt, spawna l'agente, monitora l'output, rileva il completamento, passa al task successivo. Ripete fino a esaurimento del backlog o raggiungimento del limite di iterazioni.

Configurazione avanzata

Il file .ralph-tui/config.toml controlla il comportamento:

tracker = "json"           # json | beads | beads-bv
agent = "claude"           # claude | opencode
maxIterations = 10         # limite di sicurezza

[agentOptions]
model = "sonnet"           # opus | sonnet | haiku

[errorHandling]
strategy = "skip"          # retry | skip | abort
maxRetries = 3

I tracker disponibili coprono scenari diversi: json per iniziare senza dipendenze esterne, beads per issue tracking git-backed con gerarchie, beads-bv per selezione intelligente via analisi del grafo delle dipendenze (PageRank, critical path).

Il dimensionamento dei task: dove tutto si gioca

Ogni PRD item deve essere abbastanza piccolo da completarsi in una context window. Se un task è troppo grande, l'LLM esaurisce il contesto prima di finire e produce codice scadente.

Esempi di task dimensionati correttamente: aggiungere una colonna al database con migrazione, creare un componente UI su una pagina esistente, aggiornare una server action con nuova logica, aggiungere un filtro dropdown a una lista.

Esempi di task da spezzare: "costruisci l'intera dashboard", "aggiungi l'autenticazione", "esegui il refactoring dell'API".

Il principio operativo è che il task deve essere completabile in una singola sessione agent senza degradazione della qualità. Se non riesci a descriverlo in due o tre frasi, probabilmente va diviso.

La memoria persistente: AGENTS.md e progress.txt

Ralph mantiene due canali di memoria cross-iterazione.

progress.txt (o .ralph-tui/progress.md) accumula note da ogni iterazione. Le ultime N iterazioni vengono iniettate nel prompt via {{recentProgress}}. Questo dà all'agente contesto su cosa è stato fatto senza dover rileggere il codice.

AGENTS.md è più interessante: dopo ogni iterazione, Ralph aggiorna i file AGENTS.md con i learnings. Questo è cruciale perché Amp legge automaticamente questi file, quindi le iterazioni future (e gli sviluppatori umani) beneficiano di pattern scoperti, gotcha e convenzioni.

Esempi di cosa aggiungere ad AGENTS.md: pattern scoperti ("questo codebase usa X per Y"), gotcha ("non dimenticare di aggiornare Z quando modifichi W"), contesto utile ("il pannello settings è nel componente X").

Gestione degli errori e recovery

Ralph TUI offre tre strategie per gli errori: retry per operazioni flaky (problemi di rete), skip per task non critici, abort per workflow dove qualsiasi fallimento è inaccettabile.

La persistenza della sessione implica il salvataggio dello stato in .ralph-tui-session.json: numero iterazione corrente, stati dei task, storia delle iterazioni, task attivi per crash recovery. Al resume, Ralph resetta i task stuck "in_progress" a "open" e riparte.

Quando usare Ralph, quando no

Ralph funziona meglio per task con criteri di completamento chiari ed esecuzione meccanica: grandi refactor, migrazioni di framework, aggiornamenti di dipendenze, bump di versione API su centinaia di file.

Non funziona per lavoro che richiede giudizio sfumato, comprensione profonda di un codebase ampio, o decisioni architetturali. La tecnica automatizza l'esecuzione meccanica, non le decisioni su cosa vale la pena costruire.

Mentre il loop Ralph Wiggum, come il suo personaggio eponimo, mantiene una persistenza allegra che permette agli agenti di risolvere bug complessi attraverso pura iterazione, l'autonomia crea un vuoto di governance. Il rischio è quello che viene chiamato "overbaking": l'agente che non può uscire dal loop perché deve soddisfare una completion promise potrebbe entrare in un "sycophancy loop", tentando di compiacere l'utente in modi distruttivi.

Il principio sottostante

Ralph incarna una logica "agile ma ingegnerizzata": PRD come specifica parsabile, story come unità atomiche verificabili, epic come contenitore di scope, convert come enforcer della qualità per-task, prompt template come contratto ripetibile, token COMPLETE come meccanismo deterministico di avanzamento.

Il lavoro cognitivo si sposta a monte, nella specifica. E la specifica richiede ancora quell'atto di traduzione che nessun parser può compiere: trasformare un'intenzione in un criterio verificabile. Chi scrive i quality gate? Chi decide cosa significa "fatto"?

L'automazione del loop di sviluppo non elimina l'engineering, lo concentra in un punto diverso della pipeline.