home / skills / zpankz / mcp-skillset / ralph-graceful-exit

ralph-graceful-exit skill

safe

This skill detects true Ralph Loop completion using four-signal checks and confirms graceful exit for reliable task verification.

npx playbooks add skill zpankz/mcp-skillset --skill ralph-graceful-exit

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

Files (1)

SKILL.md

2.4 KB

---
name: ralph-graceful-exit
description: |
  Detects Ralph Loop completion beyond <promise> tags. Use when checking if a task
  is complete, verifying completion status, or detecting graceful exit conditions.
  Implements 4-signal detection: test loops, done signals, completion indicators,
  and fix plan verification.
allowed-tools: Read, Grep, Bash
model: haiku
context: fork
agent: ralph-domain-agent
user-invocable: false
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "$HOME/.claude/hooks/ralph-activity-log.sh"
---

# Ralph Graceful Exit

## Purpose

Detect when a Ralph Loop iteration has truly completed its task, beyond just the `<promise>DONE</promise>` tag. This skill implements 4-signal detection to verify genuine completion.

## Integrations

| Type | References |
|------|------------|
| hooks | ralph-circuit-breaker, ralph-rate-limiter, ralph-activity-log |
| plugins | ralph-loop@claude-plugins-official |

## 4-Signal Detection

| Signal | Threshold | Detection Method |
|--------|-----------|------------------|
| test_loops | ≥3 consecutive | Only running tests, no code changes |
| done_signals | ≥2 occurrences | "done", "complete", "finished" in output |
| completion_indicators | ≥2 patterns | Strong completion language patterns |
| fix_plan_check | all items ✓ | All @fix_plan.md items checked |

## Detection Logic

When evaluating completion:

1. **Check activity log** for test-only iterations
   ```bash
   grep -c "test\|pytest\|jest\|npm test" ~/.ralph-state/activity.log
   ```

2. **Scan recent output** for done_signals patterns
   - "done", "complete", "finished", "all tests pass"
   - "implementation complete", "task finished"

3. **Look for completion_indicators** in conversation
   - Strong completion language
   - Summary of what was accomplished
   - No pending TODO items mentioned

4. **Verify fix_plan** if exists
   - Check if @fix_plan.md exists
   - Verify all checkbox items are checked `[x]`

## Exit Recommendation

If ≥2 signals detected, recommend outputting:

```
<promise>DONE</promise>
```

## Signal Weights

| Signal | Weight | Confidence |
|--------|--------|------------|
| fix_plan_check (all ✓) | 1.0 | High |
| test_loops ≥3 | 0.8 | High |
| done_signals ≥2 | 0.6 | Medium |
| completion_indicators ≥2 | 0.5 | Medium |

Total weight ≥1.5 → Strong recommendation to exit
Total weight ≥1.0 → Suggest checking completion status

Overview

This skill detects genuine completion of a Ralph Loop iteration beyond a simple <promise>DONE</promise> tag. It implements four-signal detection to verify that work is finished, combining test-loop patterns, explicit done signals, completion language, and fix-plan verification to produce an exit recommendation.

How this skill works

The skill inspects activity logs for repeated test-only runs, scans recent output for explicit done/complete/finished signals, analyzes conversation or output for strong completion language and absence of TODOs, and checks any @fix_plan.md for all checklist items marked done. It assigns weights to each signal, sums them, and recommends a graceful exit when the total meets configured thresholds.

When to use it

Before emitting a final <promise>DONE</promise> for a looped task
When verifying whether an iterative code task has genuinely finished
When confirming fixes after automated test cycles
During review of automated agent runs to avoid premature exits
When a fix plan file may indicate remaining actionable items

Best practices

Require at least two independent signals before recommending exit to avoid false positives
Prefer fix_plan verification when available; it has the highest weight
Treat repeated test-only iterations (≥3) as strong evidence of stabilization, but confirm with other signals
Ensure logs and recent output are available and recent to avoid stale conclusions
Use the weight thresholds (≥1.5 strong, ≥1.0 check) as decision guides, not absolute rules

Example use cases

An agent runs tests repeatedly and outputs several 'done' messages—use this skill to confirm a safe exit
A developer loop with a @fix_plan.md checks all items—skill recommends a graceful DONE
Continuous integration runner that needs to decide if an iterative fix cycle completed
Automated assistants that should avoid closing tasks when TODOs or partial summaries remain

FAQ

What counts as a done signal?

Short explicit phrases like 'done', 'complete', 'finished', or 'all tests pass' in recent output. Two occurrences are required to meet the done_signals threshold.

How does the fix plan affect the decision?

A fully checked @fix_plan.md (all [x] items) carries the highest weight and can push the total to a strong recommendation when combined with other signals.