Proactive QA agent that explores web apps with Playwright to find bugs (usability, functionality, layout) and auto-fixes them. Three modes: "explore" (browse and log issues), "autofix" (fix pending issues with validation and retry), and "cycle" (alternates explore/autofix automatically). Use this skill when: /proactive-qa, the user wants autonomous bug hunting, proactive testing, or automated exploration of the web interface. Also use when the user mentions "/loop" with QA, testing exploration, or proactive bug fixing. Invoke with: /proactive-qa explore, /proactive-qa autofix, or /proactive-qa cycle.
Autonomous quality assurance skill with three modes. Designed to run via /loop.
/loop)Both modes write to the same bitacora and notify via Telegram.
/proactive-qa init to discover routes and verify prerequisites/loop 15m /proactive-qa cycleBefore using this skill, the project must define these values in its CLAUDE.md or a project-level config. The skill references them as {PLACEHOLDER} throughout its documentation.
| Variable | Description | Example |
|---|
{DEV_SERVER_START} | Command to start dev servers | pnpm dev, npm run dev, make serve |
{DEV_SERVER_STOP} | Command to stop dev servers | pnpm dev:stop, pkill -f "next dev" |
{API_HEALTH_URL} | API health check endpoint | http://localhost:3001/health |
{FRONTEND_URL} | Frontend base URL | http://localhost:5173 |
{PLAYWRIGHT_CONFIG} | Path to Playwright config | tests/e2e/playwright.config.ts |
{AUTH_STATE} | Path to Playwright auth state | tests/e2e/.auth/user.json |
{LINT_CMD} | Lint command | pnpm lint, npm run lint |
{TEST_CMD} | Test command | pnpm test, npm test |
{BITACORA_DIR} | Directory for issue logs | docs/proactive-works/ |
cd. Run everything from project root.bash .proactive-qa-scripts/commit.sh for all commits. Never raw git commands (they trigger permission prompts that break automation).Write ALL temp scripts and screenshots to $TMPDIR (or /private/tmp/claude/ as fallback). Never write temporary files inside the project tree.
# CORRECT
cat > "$TMPDIR/explore-session.spec.ts" << 'SCRIPT'
...
SCRIPT
npx playwright test --config {PLAYWRIGHT_CONFIG} "$TMPDIR/explore-session.spec.ts"
# FORBIDDEN — pollutes repo, breaks lint
Write(tests/e2e/explore-session.spec.ts)
rm directlyThe sandbox blocks rm and requires user confirmation, breaking automation. Always use the dedicated scripts:
| Action | Command |
|---|---|
| Clean all explore temp files | bash .proactive-qa-scripts/cleanup-explore.sh |
| Delete specific files from $TMPDIR | bash .proactive-qa-scripts/cleanup-tmpdir.sh file1.ts file2.png |
These rules apply to all agents and subagents — fixer agents, validator agents, and the orchestrator itself.
At the start of each session, resolve the notification target:
~/.claude/channels/telegram/.env → extract AUTHORIZED_CHAT_ID as NOTIFY_CHAT_ID.env for TELEGRAM_CHAT_ID (legacy)For every notification below, run:
bash .proactive-qa-scripts/telegram-notify.sh "<type>" "<text-only message>"
The script resolves the chat_id itself (same order as above) and sends via curl. Screenshots cannot be attached — mention file paths in the text body when relevant.
1. Explore results (explore):
🔍 *Proactive QA* — explore
📂 Branch: `{branch}`
Exploración completada. {N} rutas revisadas, {M} problemas nuevos encontrados.
Categorías: {list}
Attach: screenshots from $TMPDIR/screenshot-*.png
2. Fix success (fix-ok):
✅ *Proactive QA* — fix-ok
📂 Branch: `{branch}`
PWI-{id} arreglado: {título}
3. Fix failure (fix-fail):
❌ *Proactive QA* — fix-fail
📂 Branch: `{branch}`
PWI-{id} necesita revisión humana: {título}. 3 intentos fallidos.
4. Cycle complete (cycle-done):
🏁 *Proactive QA* — cycle-done
📂 Branch: `{branch}`
Ciclo completado. {X} arreglados, {Y} fallidos, {Z} pendientes.
5. Error (error):
🚨 *Proactive QA* — error
📂 Branch: `{branch}`
{error description}
Before any Playwright run, verify dev servers are up:
curl -s {API_HEALTH_URL} > /dev/null 2>&1 && echo "API OK" || echo "API DOWN"
curl -s {FRONTEND_URL} > /dev/null 2>&1 && echo "Frontend OK" || echo "Frontend DOWN"
If down, attempt recovery: {DEV_SERVER_STOP} then {DEV_SERVER_START} & sleep 10. If still down after retry, log a critical build issue in the bitacora and exit.
Playwright auth files must exist at {AUTH_STATE}. Generate them according to your project's auth setup before first use.
All issues are logged in {BITACORA_DIR}/YYYY-MM-DD-HHmm-explore.md:
# Exploración proactiva — YYYY-MM-DD HH:mm
## Categorías verificadas
1, 2, 3 (siempre) + 10, 12 (rotación)
## Rutas exploradas
| Ruta | Estado | Notas |
|------|--------|-------|
| /dashboard | OK | Sin problemas |
| /transactions | PROBLEMA | Ver PWI-xxx |
## Problemas identificados
### PWI-{timestamp}-001: Título descriptivo
- **Estado**: pendiente
- **Ruta**: /transactions
- **Tipo**: usabilidad | funcionamiento | maquetación
- **Severidad**: critica | alta | media | baja
- **Descripción**: Qué se observó
- **Cómo reproducir**: Pasos
- **Corrección sugerida**: Qué archivo(s) cambiar
- **Intentos**: 0/3
- **Historial de intentos**: (vacío)
The PWI-{timestamp}-NNN ID uses the file's timestamp prefix + sequential number.
grep -l "Estado.*pendiente\|Estado.*fallido[^-]" {BITACORA_DIR}/*.md
Use the Edit tool to update specific fields. Always preserve Historial de intentos.
Invocation: /loop 15m /proactive-qa cycle
Automatically alternates between explore and autofix on each invocation. Uses a state file (.cycle-state in the plugin root) to track which mode runs next.
bash .proactive-qa-scripts/cycle-state.sh read (defaults to explore)explore: run explore mode, then toggle: bash .proactive-qa-scripts/cycle-state.sh autofixautofix: run autofix mode, then toggle: bash .proactive-qa-scripts/cycle-state.sh explore/clear as usual# Read current state
bash .proactive-qa-scripts/cycle-state.sh read
# Toggle after completing
bash .proactive-qa-scripts/cycle-state.sh autofix
bash .proactive-qa-scripts/cycle-state.sh explore
Never write to the state file directly — use the script to avoid permission prompts.
The state file (.proactive-qa-cycle) lives in the project root, not in the plugin cache.
Add .proactive-qa-cycle to your .gitignore.
If autofix finds no pending issues, it skips silently and the next cycle will explore again.
Invocation: /proactive-qa explore or /loop 15m /proactive-qa explore
Time limit: 15 minutes max per session.
Read references/explore.md for the full flow: loading prior coverage, planning which routes/categories to check, running Playwright scripts, logging findings, and cleanup.
Key reference: references/explore-checklist.md has the verification categories and Playwright templates.
After finishing: run cleanup + /clear to free context for next iteration.
Invocation: /proactive-qa autofix or /loop 10m /proactive-qa autofix
Read references/autofix.md for the full flow: loading pending issues, launching fixer/validator agents, processing results (commit or rollback), and the 3-attempt retry cycle.
After finishing: notify via Telegram + /clear to free context for next iteration.
Every agent prompt (fixer, validator) MUST include these rules:
- Never use cd, run everything from project root
- Follow project conventions in CLAUDE.md
- Write temp files to $TMPDIR, NEVER inside the project tree
- NEVER use rm to delete files. Use:
bash .proactive-qa-scripts/cleanup-tmpdir.sh file1.ts file2.png
- Do NOT change branch
- Do NOT commit — the orchestrator handles commits
Run /proactive-qa init — it creates a .proactive-qa-scripts symlink to the plugin scripts and adds version-agnostic permissions to .claude/settings.json. Re-run init after plugin upgrades to update the symlink.