Proactive QA

Safety Rules

• NEVER change git branch. All work happens on the current branch.
• NEVER use cd. Run everything from project root.
• Use bash .proactive-qa-scripts/commit.sh for all commits. Never raw git commands (they trigger permission prompts that break automation).
• Respect all existing hooks (lint, tests, protect-files).

Temporary Files — ALWAYS use $TMPDIR

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)

Cleanup — NEVER use rm directly

The sandbox blocks rm and requires user confirmation, breaking automation. Always use the dedicated scripts:

These rules apply to all agents and subagents — fixer agents, validator agents, and the orchestrator itself.

Notifications

Setup — Chat ID Resolution

At the start of each session, resolve the notification target:

1. Read ~/.claude/channels/telegram/.env → extract AUTHORIZED_CHAT_ID as NOTIFY_CHAT_ID
2. If that file is missing or the key is empty, check project .env for TELEGRAM_CHAT_ID (legacy)
3. If neither available, skip all notifications — log to transcript only

Dispatch Rule

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.

Notification Types

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}

Server Health Check

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.

Auth State

Playwright auth files must exist at {AUTH_STATE}. Generate them according to your project's auth setup before first use.

Bitacora Format

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.

Finding pending work

grep -l "Estado.*pendiente\|Estado.*fallido[^-]" {BITACORA_DIR}/*.md

Updating issues

Use the Edit tool to update specific fields. Always preserve Historial de intentos.

Mode: Cycle (alternating explore/autofix)

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.

How it works

1. Read state: bash .proactive-qa-scripts/cycle-state.sh read (defaults to explore)
2. If state = explore: run explore mode, then toggle: bash .proactive-qa-scripts/cycle-state.sh autofix
3. If state = autofix: run autofix mode, then toggle: bash .proactive-qa-scripts/cycle-state.sh explore
4. After finishing, run cleanup + /clear as usual

State management

# 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.

Mode: Explore

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.

Mode: Autofix

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.

Common Rules for All Subagents

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

Setup — Permissions for Autonomous Execution

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.