pua-loop

Overview of pua-loop skill

What pua-loop is for

pua-loop is a loop-execution skill for long, multi-step implementation tasks where you want the agent to keep iterating without stopping to ask you questions. It combines an autonomous retry loop with the repo’s pua:pua behavior rules, so the agent keeps checking work, validating, fixing, and rerunning until it can declare completion.

Best fit for pua-loop

The best readers for the pua-loop skill are users working on coding or workflow tasks that can be verified locally: bug fixes, refactors, feature completion, test repair, and repetitive cleanup. It is especially relevant for pua-loop for Workflow Automation when interruption costs more than a few imperfect assumptions.

Real job-to-be-done

What users usually want is not “a clever prompt,” but a way to hand off a bounded task and avoid babysitting the agent every few minutes. pua-loop is designed for that handoff. Its key promise is autonomous iteration: inspect current state, make a change, run validation, diagnose failures, and continue.

What makes pua-loop different

The main differentiator is that pua-loop is opinionated about persistence. The skill explicitly forbids asking the user questions during loop mode and expects the agent to exhaust alternatives before giving up. It also persists loop state through a local file so the behavior survives context compaction better than an ordinary one-shot prompt.

Important adoption caveat

This is not a general-purpose “better coding” skill. pua-loop is strongest when the task has a clear success condition and available checks. If your task is ambiguous, requires frequent product decisions, or depends on external approvals, ordinary interactive prompting is usually safer.

How to Use pua-loop skill

Install context before you rely on it

The repository excerpt shows only SKILL.md, and the skill expects support from the broader tanweai/pua repo, including a setup script path and the pua:pua core skill behavior. Before serious use, review the repo root and confirm the referenced loop script and core skill are present in your installed environment.

How pua-loop is triggered

The documented trigger is /pua:pua-loop "task description". The description also lists natural-language triggers such as loop mode, 自动循环, and 一直跑, but the slash command is the least ambiguous way to invoke pua-loop usage reliably.

What happens after launch

When started, the skill runs a setup command that creates .claude/pua-loop.local.md. That file stores the task plus the loop protocol. A stop hook then uses that file to keep feeding instructions back into the agent on each iteration. In practice, that means the agent can continue the same task pattern across repeated runs without you re-explaining the workflow.

Inputs that make pua-loop work well

Give pua-loop four things up front:

1. The task outcome
2. The repo or folder scope
3. The validation command
4. Any hard constraints

A weak input:

• “Fix the app.”

A strong input:

• “Use pua-loop to fix the failing login flow in apps/web. Success means pnpm test --filter web passes and the OAuth callback no longer throws a 500. Do not change the database schema. Prefer the smallest safe fix.”

That stronger version reduces wasted iterations because the agent knows where to work, how to verify, and what not to touch.

Turn a rough goal into a complete pua-loop prompt

A practical pua-loop guide pattern is:

• Task: what should be built or fixed
• Scope: files, package, or service boundaries
• Verification: tests, lint, build, smoke check
• Constraints: no schema changes, no new deps, keep API stable
• Priority: fastest safe fix vs deeper refactor

Example:

• /pua:pua-loop "Resolve TypeScript errors in packages/api only. Run pnpm --filter api build after each meaningful fix. Do not modify public endpoint contracts. Stop only when build passes and no new lint errors are introduced."

Repository files to read first

Start with:

• skills/pua-loop/SKILL.md

Then inspect the parent repo for:

• the pua:pua core skill definition
• any scripts/setup-pua-loop.sh
• hook documentation or Claude plugin setup files

That reading order matters because pua-loop install decisions depend less on prose and more on whether your local environment actually supports the setup script and stop-hook loop.

What the loop is actually doing each iteration

The skill’s core rule set is simple:

• load pua:pua behavior
• do not ask the user questions
• do not stop early with “cannot solve”
• after each change, validate, find issues, fix, and validate again

This makes pua-loop closer to an autonomous repair cycle than a normal assistant interaction.

When to use pua-loop instead of a normal prompt

Use pua-loop when:

• success can be checked automatically
• you expect several rounds of fix-and-verify
• you want fewer interruptions
• the repo has runnable commands

Skip it when:

• the task needs product judgment every step
• the agent lacks access to tests or runtime checks
• a wrong assumption would be expensive

Practical workflow for first-time use

A sensible first run:

1. Start with one bounded issue, not a large rewrite.
2. Include the exact validation command.
3. Keep scope narrow to one package or feature.
4. Let the loop run.
5. Review the final changes and only then widen usage.

This reduces the main adoption risk: overconfident autonomous edits on under-specified tasks.

Cancellation and safety boundaries

The skill documents two stop paths: /cancel-pua-loop or deleting .claude/pua-loop.local.md. Treat those as required operational knowledge before enabling autonomous iteration. If you cannot easily inspect or remove that file in your environment, pua-loop skill may be a poor fit for your setup.

pua-loop skill FAQ

Is pua-loop good for beginners?

Yes, but only for well-scoped tasks. Beginners often benefit from the automation, but they are also more likely to give vague instructions. If you are new, start with a failing test or build error, not an open-ended architecture request.

Does pua-loop replace ordinary prompting?

No. pua-loop is better for execution loops, not for collaborative exploration. If you still need to choose an approach, compare options, or clarify requirements, use a normal prompt first and switch to pua-loop once the plan is settled.

What is the biggest blocker to successful pua-loop install?

Usually environment mismatch. The skill references a setup script and a stop-hook-driven loop. If your local Claude/plugin setup does not provide those pieces, the markdown alone will not produce the intended autonomous behavior.

Can pua-loop work without tests?

It can, but quality drops. Without tests, build commands, or smoke checks, the agent has less signal to know whether each iteration improved the task. In that case, pua-loop usage becomes more guess-driven and less trustworthy.

How is pua-loop different from just saying “keep trying”?

A plain prompt can ask for persistence, but pua-loop adds a specific operational pattern: state persistence via a local file, repeated validation, explicit no-question mode, and completion signaling. That structure is the real reason to install it.

When should I not use pua-loop for Workflow Automation?

Do not use pua-loop for Workflow Automation when the workflow depends on human approval gates, external credentials, ambiguous business rules, or tasks where “done” is subjective. Autonomous looping helps only when completion can be checked.

How to Improve pua-loop skill

Give pua-loop a measurable finish line

The fastest way to improve pua-loop results is to define completion in machine-checkable terms. “Make it work” is weak. “All auth tests pass, build succeeds, and /login/callback returns 200” is strong. The skill is built around iteration, so it needs a target it can verify.

Narrow scope to reduce bad autonomous decisions

Because pua-loop avoids asking follow-up questions, broad tasks create unnecessary risk. Instead of “refactor payments,” say “fix duplicate retry handling in services/payments/retry.ts without changing webhook payloads.” Narrow scope improves both speed and safety.

Supply constraints that prevent destructive fixes

Good constraints are not extra fluff; they keep the loop from solving the wrong problem. Useful examples:

• do not add dependencies
• do not change schema
• keep API responses backward compatible
• prefer minimal patch over rewrite

These directly improve the quality of pua-loop output.

Use the strongest available validation command

If multiple checks exist, choose the most relevant one, not the noisiest one. For a UI bug, a targeted test suite is better than an entire monorepo run. For a type issue, tsc on the affected package may be better than broad linting. Better validation means better loop decisions.

Expect failure modes from missing context

Common pua-loop failure modes are predictable:

• vague task descriptions
• missing repo path or module scope
• no validation command
• hidden non-technical requirements
• autonomous changes in the wrong package

Most of these are fixed by improving the initial prompt, not by rerunning unchanged.

Iterate after the first run with sharper instructions

If the first pua-loop pass gets close but not all the way there, do not simply say “try again.” Add the missing signal:

• what still fails
• which files were touched incorrectly
• what tradeoff to prefer
• which validation result matters most

That turns a second run into a guided correction rather than more blind looping.

Improve trust by reading the core dependency

Since pua-loop inherits behavior from pua:pua, advanced users should inspect that core skill before adoption. If you dislike its pressure style or decision rules, you may not want this loop wrapper at all. This is one of the most important repo-reading steps for an informed install decision.

Start with bounded automation, then expand

For most teams, the best pua-loop guide is gradual adoption: first use it on repair tasks with clear checks, then on small feature completion, and only later on larger automation flows. That sequence lets you validate whether the loop behavior fits your repo and risk tolerance.