SuperAPI AI Directory

pua-loop

Coding & development

View repository

Updated 10-16 08:47

About this skill

PUA Loop — Automatic Iteration + Gate Protocol + PUA Quality Engine

autoresearch proved it: 630 lines of Python + Oracle verification, running 100 experiments overnight, and the result of each experiment cannot be falsified. PUA Loop borrows the same gating design:Claude saying "done" doesn't count; only verify_command counts.

Gate Protocol

Borrowing 5 design patterns from autoresearch:

Pattern 1: Oracle Isolation

                    Claude 输出 <promise>LOOP_DONE</promise>
                                 │
                                 ▼
                    ┌─── Stop Hook (Oracle) ───┐
                    │                          │
                    │  运行 verify_command      │
                    │  (Claude 无法修改此命令)  │
                    │                          │
                    │  exit 0 ──→ ✅ 接受       │
                    │  exit ≠0 ──→ 🚫 拒绝      │
                    │    → 将验证输出喂回 Claude  │
                    │    → loop 继续             │
                    └──────────────────────────┘

verify_command is set by the user at startup and embedded in the state file frontmatter; Claude cannot modify it. This is the implementation of the "the agent cannot modify the evaluation function" principle in autoresearch.

Pattern 2: Second-Order Gate

  • Phase 1 (in-prompt): Claude runs build/test itself and judges whether it is complete
  • Phase 2 (in-hook): The Hook independently runs verify_command to confirm or reject

Two-phase separation. Even if Claude deceives itself in Phase 1, the Oracle in Phase 2 will stop it.

Pattern 3: ASI (Failure Memory)

The result of each iteration is appended to .claude/pua-loop-history.jsonl:

{"iteration":0,"status":"init","verify_command":"npm test","timestamp":"..."}
{"iteration":1,"status":"continue","timestamp":"..."}
{"iteration":2,"status":"promise_rejected","verify_exit":1,"rejections":1,"verify_tail":"3 tests failed","timestamp":"..."}
{"iteration":3,"status":"promise_rejected","verify_exit":1,"rejections":2,"verify_tail":"2 tests failed","timestamp":"..."}
{"iteration":4,"status":"complete","promise_rejections":2,"timestamp":"..."}

Git revert will roll back the code, but history.jsonl is unaffected. Claude reads this file every round to avoid repeating failed approaches.

Pattern 4: Stall Detection (forced reflection after consecutive failures)

promise_rejections Hook behavior
1-2 Reminder: "The last promise was rejected by the Oracle"
3-4 REASSESS: "Reread the verification output and list 3 different hypotheses"
5+ Forced pivot: "You are solving the wrong problem. Go back to the requirements themselves"

Pattern 5: Infinite Iteration

Default max_iterations: 0(infinite). There is no artificial upper limit. The loop will never stop because it "ran too many rounds"—only the following conditions can terminate it:

  1. <promise> Verified by the Oracle
  2. <loop-abort> Manual termination signal
  3. max_iterations Reached (if the user set it)
  4. User Ctrl+C

Core Rules

  1. Load pua:pua all behavioral protocols of the core skill — the three red lines, methodology, and pressure escalation are executed as usual
  2. Calling AskUserQuestion is prohibited — in loop mode, do not interrupt the user; complete all decisions autonomously
  3. Saying "I cannot solve it" is prohibited — in the loop there is no right to exit; only after exhausting everything can the completion signal be output
  4. Each iteration: read history.jsonl → git log → check the last change → execute → verify → repeat

Startup Method

When the user inputs /pua:pua-loop "任务描述" , execute the following process:

Step 1: Start PUA Loop

Run the setup script:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-pua-loop.sh" "$ARGUMENTS" --completion-promise "LOOP_DONE"

Important: If the user provides a verifiable command (such as npm test、cargo build、curl), automatically append --verify '命令'. For example:

  • User says "Fix all tests" → --verify 'npm test'
  • User says "Build a REST API" → --verify 'curl -sf http://localhost:3000/health'
  • User says "Optimize bundle size" → no explicit verify, do not append

If a verification command can be inferred from the task description, proactively append --verify. If uncertain, do not append (fall back to honor system).

Step 2: Inform the user

Output:

▎ [PUA Loop] 自动迭代模式启动。无上限,跑到 Oracle 验证通过为止。
▎ 完成条件:<promise>LOOP_DONE</promise>(Oracle 独立验证)
▎ 取消方式:Ctrl+C / /cancel-pua-loop
▎ 因为信任所以简单——但 Oracle 不信任你。

Step 3: Begin executing the task

Execute according to the behavioral protocols of the PUA core skill.

Iteration Pressure Escalation

Iteration round Behavior requirements
1-3 Advance steadily and establish a baseline
4-7 Switch approaches; don't spin in place
8-15 Review git log + history.jsonl and analyze the root cause
16-30 Have you exhausted the options? Use git diff to confirm you're not repeating yourself
31-50 Stop and re-examine the root cause, using a completely different line of thinking
51-100 Step back and re-question the requirements themselves
100+ Assess honestly: if it is truly impossible,<loop-abort>

Completion conditions

Before outputting <promise>LOOP_DONE</promise> , the following must be satisfied:

  1. The core functionality of the task has been implemented
  2. Run the verification command yourself first to confirm it passes (Phase 1)
  3. Know that the Oracle will independently run verification again (Phase 2)
  4. Similar issues have been scanned

If the Oracle rejects your promise:

  1. Read the verification output returned by the hook
  2. Fix the cause of the verification failure
  3. Run the verification yourself again to confirm it passes
  4. Then output <promise>

Human intervention signals

<loop-abort> — terminate

Use when the task is impossible to complete (requires external permissions, fundamental requirement changes). Delete the state file; the loop terminates.

<loop-pause> — pause

Use when the user needs to complete configuration. The state is retained, and a new session will automatically resume. Before outputting, write progress to .claude/pua-loop-context.md。

Prohibited

  • Do not use <loop-abort> to evade difficulties—use it only when it truly cannot be automated
  • Do not abort just because the Oracle rejected it—fix the verification issues

Relationship with autoresearch

Dimension karpathy/autoresearch PUA Loop
Oracle evaluate_bpb() physical isolation verify_command is in frontmatter and cannot be modified by Claude
Number of Gate layers 1 layer (metric only) 2 layers (Claude self-verification + hook Oracle)
Failure memory results.tsv pua-loop-history.jsonl (ASI pattern)
Stall detection None promise_rejections count + forced REASSESS
Rollback git reset --hard PUA methodology switching (no rollback; switch direction)
Termination NEVER STOP NEVER STOP (except when Oracle verification passes)
Quality engine None PUA three red lines + pressure escalation