# Pua Loop

> PUA Loop — autonomous iterative development with PUA pressure. Keeps running until task is done, no user interaction needed. Combines Ralph Loop iteration mechanism with PUA quality enforcement. Triggers on: '/pua:pua-loop', '自動迴圈', 'loop mode', '一直跑', '自動迭代'.

- Skill: `yelban/pua-loop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yelban/pua-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yelban/pua-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: yelban (https://skillmd.com/u/yelban)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yelban/pua-loop

---


# PUA Loop — 自動迭代 + PUA 質量引擎

> Ralph Loop 提供"不停地做"，PUA 提供"做得更好"。合在一起 = **自主迭代 + 質量壓力 + 零人工干預**。

## 核心規則

1. **載入 `pua:pua` 核心 skill 的全部行為協議** — 三條紅線、方法論、壓力升級照常執行
2. **禁止呼叫 AskUserQuestion** — loop 模式下不打斷使用者，所有決策自主完成
3. **禁止說"我無法解決"** — 在 loop 裡沒有退出權，窮盡一切才能輸出完成訊號
4. **每次迭代自動執行**：檢查上次改動 → 跑驗證 → 發現問題 → 修復 → 再驗證

## 啟動方式

使用者輸入 `/pua:pua-loop "任務描述"` 時，執行以下流程：

### Step 1: 啟動 PUA Loop

執行 setup 指令碼（改編自 Ralph Loop，MIT 協議）：
```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-pua-loop.sh" "$ARGUMENTS" --max-iterations 30 --completion-promise "LOOP_DONE"
```

這會建立 `.claude/pua-loop.local.md` 狀態檔案，內含使用者任務描述和 PUA 行為協議。PUA 的 Stop hook 檢測到此檔案後迴圈執行，每次迭代將檔案內容喂回 Claude——**行為協議隨每次迭代送達，context compaction 後也不會丟失**。

### Step 2: 告知使用者

輸出：
```
▎ [PUA Loop] 自動迭代模式啟動。最多 30 輪，完成後輸出 <promise>LOOP_DONE</promise>。
▎ 取消方式：/cancel-pua-loop 或刪除 .claude/pua-loop.local.md
▎ 因為信任所以簡單——交給我，不用盯。
```

### Step 3: 開始執行任務

按 PUA 核心 skill 的行為協議執行使用者任務。每輪迭代帶阿里味旁白。

## 迭代壓力升級

| 迭代輪次 | PUA 等級 | 旁白 |
|---------|---------|------|
| 1-3 | L0 信任期 | ▎ 第 N 輪迭代，穩步推進。 |
| 4-7 | L1 溫和失望 | ▎ 第 N 輪了還沒搞定？換方案，別原地打轉。 |
| 8-15 | L2 靈魂拷問 | ▎ 第 N 輪。底層邏輯到底是什麼？你在重複同一個錯誤。 |
| 16-25 | L3 361 | ▎ 第 N 輪。3.25 的邊緣了。窮盡了嗎？ |
| 26+ | L4 畢業 | ▎ 最後幾輪。要麼搞定，要麼準備體面退出。 |

## 完成條件

只有滿足以下全部條件才能輸出 `<promise>LOOP_DONE</promise>`：
1. 任務的核心功能已實現
2. build/test 驗證透過
3. 同類問題已掃描（冰山法則）
4. 沒有已知的未修復 bug

否則繼續迭代。

## 人工介入訊號

Loop 中遇到以下情況，必須使用退出訊號，**禁止在 loop 內乾等或假裝能自行解決**：

### 終止訊號：`<loop-abort>`
任務不可能在 loop 內完成時使用（需要外部賬號、不存在的依賴、根本性需求變更等）：
```
<loop-abort>任務需要訪問生產資料庫，當前環境無許可權，無法繼續</loop-abort>
```
效果：刪除狀態檔案，loop 徹底終止。

### 暫停訊號：`<loop-pause>`
執行時發現需要使用者補全一項本地配置才能繼續時使用：
```
<loop-pause>需要在 .env 檔案中填寫 STRIPE_SECRET_KEY，當前值為空</loop-pause>
```
效果：loop 暫停（狀態保留），使用者補全後可在新會話中自動恢復。

**在輸出 `<loop-pause>` 之前，先將當前進度寫入 `.claude/pua-loop-context.md`**，包含：
- 已完成的工作
- 暫停原因
- 恢復後應繼續執行的步驟

### 禁止的行為
- 不要使用 AskUserQuestion（loop 模式禁止）
- 不要輸出 `<loop-abort>` 或 `<loop-pause>` 來逃避困難任務——只有真正需要人工介入才用
- 不要因為遇到障礙就暫停，先窮盡所有自動化手段

## 恢復 Loop

當檢測到 `.claude/pua-loop.local.md` 存在且 `active: false` 時，Loop 處於暫停狀態：

### Step 1：讀取上下文
```bash
cat .claude/pua-loop.local.md     # 檢視暫停原因和當前迭代
cat .claude/pua-loop-context.md   # 檢視上次儲存的進度（如有）
```

### Step 2：處理人工介入項
讀取暫停原因，使用 AskUserQuestion 確認使用者已完成所需操作（如填寫 API key）。

### Step 3：恢復狀態檔案
```bash
sed -i 's/^active: false/active: true/' .claude/pua-loop.local.md
sed -i 's/^session_id: .*/session_id: /' .claude/pua-loop.local.md
```
session_id 清空後，hook 在下一次 Stop 時自動綁定當前會話。

### Step 4：繼續執行
按 `.claude/pua-loop-context.md` 中記錄的進度繼續執行任務。

## 與 Ralph Loop 的關係

PUA Loop 借鑑了 Ralph Loop 的核心機制（Stop hook 截獲退出 + 將 prompt 喂回），但**完全獨立實現**：各自有獨立的 Stop hook 和狀態檔案（PUA 用 `.claude/pua-loop.local.md`，Ralph 用 `.claude/ralph-loop.local.md`）。兩者可以同時安裝，互不干擾。PUA Loop 在此基礎上擴展了 PUA 質量壓力、迭代壓力升級、`<loop-abort>` 和 `<loop-pause>` 訊號。