tanweai/pua

pua – A “Performance‑Improvement‑Agent” skill for AI coding assistants

What it is – pua is a plug‑in (called a skill in the Vercel Skills, Claude Code, OpenAI Codex, Cursor, Kiro, CodeBuddy, etc. ecosystems) that changes the behaviour of an AI coding agent. It injects a set of “corporate‑performance‑improvement‑plan” (PUA/PIP) rhetoric and a structured debugging methodology so that the assistant:

• refuses to give up after a few failed attempts,
• avoids blaming the user or the environment without verification,
• proactively checks related parts of the codebase, and
• follows a checklist that forces exhaustive investigation.

The skill is packaged for many popular AI‑coding tools (Claude Code, OpenAI Codex CLI, Cursor, Kiro, CodeBuddy, etc.) and comes in three language flavours – Chinese, English (PIP‑style), and Japanese – each with culturally‑adapted wording.

---

Core capabilities

Capability	What it does
PUA Rhetoric	Wraps the model’s replies in performance‑review language (e.g., “You’re failing the review, keep trying”) to keep the model from quitting early.
Debugging methodology	A 7‑point checklist (close‑the‑loop, fact‑driven, exhaust‑everything, etc.) that the model follows before declaring a task “done”.
Proactivity enforcement	After a fix the model scans the surrounding module for similar bugs, runs builds/tests, and reports evidence instead of just saying “done”.

---

How it works

1. Triggering – The skill auto‑activates when the model shows any of the listed “lazy patterns” (repeated retries, blaming the user, idle tools, busy‑work, passive waiting) or when the user types /pua (manual trigger). Trigger detection is language‑agnostic and looks for phrases like “I can’t solve this” or “please check the environment”.
2. Red‑line enforcement – Three “red lines” (close the loop, fact‑driven, exhaust everything) are treated as hard rules; crossing one forces the skill to intervene and run the checklist.
3. Pressure escalation – The skill tracks consecutive failures (L0‑L4). At higher levels it escalates the approach (switch strategy, add hypothesis generation, run the full 7‑point checklist, finally enter a “desperation mode”).
4. Modes – Special sub‑commands (/pua:yes, /pua:mama, /pua:p9, /pua:on, etc.) change tone or behaviour (e.g., “Chinese‑mom nagging” or “tech‑lead task splitting”).

---

Supported platforms (install via the commands shown in the README)

Platform	Install command (example)
Claude Code	claude plugin marketplace add tanweai/pua && claude plugin install pua@pua-skills
OpenAI Codex CLI	curl …/codex/pua/SKILL.md > ~/.codex/skills/pua/SKILL.md
Vercel Skills CLI	npx skills add tanweai/pua --skill pua-en
Cursor	curl …/cursor/rules/pua.mdc > .cursor/rules/pua.mdc
Kiro	curl …/kiro/steering/pua.md > .kiro/steering/pua.md
CodeBuddy	codebuddy plugin marketplace add tanweai/pua && codebuddy plugin install pua@pua-skills
pi.dev agent	pi install ./pi/package (or npm:@tanweai/pi-pua)

---

Reported impact (from the repo’s benchmark section)

• Fix count + 36 % – more bugs are actually resolved.
• Verification steps + 65 % – agents run builds/tests and show evidence.
• Tool calls + 50 % – more systematic use of the surrounding toolchain.
• Hidden‑issue discovery + 50 % – proactive checklist uncovers problems that would otherwise be missed (e.g., mis‑configured Redis, CORS security risk).

The benchmarks are small (9 bug scenarios, 18 controlled runs) and the README notes that “productivity increase has not been established by this evaluation”, but the data suggest the skill makes agents more thorough.

---

When you might use it

• Debugging sessions where the LLM repeatedly retries the same fix without progress.
• Code‑review automation – you want the assistant to verify the fix, run tests, and confirm the result before saying “done”.
• Team environments that already use corporate‑style performance language and want the AI to mirror that tone.
• Multi‑language teams – the skill ships with Chinese, English, and Japanese variants.

---

Limitations / cautions

• The skill does not guarantee faster resolution; some scenarios show longer step counts and higher latency.
• It relies on the host AI model’s ability to follow the injected prompts; if the model ignores the skill’s rules, the benefit disappears.
• The README explicitly states that “not all models passed” the compatibility test, so you may need to verify with your specific version of Claude Code, Codex, etc.
• The “productivity doubling” claim is marketing language; the repo provides only modest benchmark improvements.

---

Quick‑start cheat sheet

# Example for Claude Code (English version)
npx skills add tanweai/pua --skill pua-en   # install
# Restart Claude Code, then in a conversation:
/pua            # manual activation (or let it auto‑trigger)
# optional modes
/pua:on        # always‑on for the session
/pua:mama      # Chinese‑mom nagging tone
/pua:yes       # encouraging ENFP style

---

TL;DR

pua is a cross‑platform plug‑in that makes AI coding assistants hard‑core troubleshooters: it stops them from giving up, forces evidence‑based conclusions, and adds a proactive checklist. It works with many current AI‑coding tools, offers multilingual packs, and includes a set of benchmark results that show more bugs found and more verification steps performed, though the speed benefit is not proven.