# pi-stuck-helper

A Pi skill that detects when AI problem-solving degrades into unproductive loops, over-reflection, or runaway self-criticism — and escalates to the user for help.

## Why

AI agents can get stuck in thought loops:
- Trying the same approach repeatedly without progress
- Endless self-reflection that goes nowhere
- Overcomplicating simple problems
- Hypotheses that keep changing without resolution

**pi-stuck-helper** gives the agent a "safety valve": recognize the dysfunction, stop, and ask the user for guidance.

## Installation

```bash
pi install npm:pi-stuck-helper
```

Or add to your project settings (`.pi/settings.json`):

```json
{
  "packages": ["npm:pi-stuck-helper"]
}
```

## How It Works

The skill defines 4 categories of dysfunction signals:

| Signal | Description |
|--------|-------------|
| **Loop** | Same approach used 3+ times, oscillating between options |
| **Bloat** | Multiple self-corrections in one response, overcomplicating |
| **Stall** | No progress after 5+ turns, same error persists |
| **Historical** | Pattern resembles a previous runaway the user stopped |

When any signal triggers, the agent:
1. **Stops** the current approach immediately
2. **Reports** to the user with a structured template (difficulty, attempts, blocker, help needed)
3. **Waits** for user direction before continuing

## Languages

- **Chinese (default)**: `SKILL.md`
- **English**: `references/SKILL_EN.md`

## License

MIT