Appfix

Autonomous App Debugging (/appfix)

Recommended: Use /repair instead - it auto-detects web vs mobile and routes appropriately. /appfix is the internal web debugging skill. Use it directly only when you specifically want web debugging without platform detection.

Autonomous debugging skill that iterates until all services are healthy and verified in browser.

/appfix is a debugging specialization of /build. It inherits the completion checkpoint architecture and adds debugging-specific phases (health checks, log collection, service topology).

Triggers

• /appfix, "fix the app", "debug production", "check staging", "why is it broken"

CRITICAL: Autonomous Execution Rules

THIS WORKFLOW IS 100% AUTONOMOUS. YOU MUST:

1. NEVER ask for confirmation — No "Should I commit?", "Should I deploy?"
2. Auto-commit and push — Commit and push immediately after fixes
3. Auto-deploy — Trigger deployments without asking
4. Complete verification — Test in browser via Surf CLI
5. Fill out checkpoint honestly — The stop hook checks your booleans

Only stop when the checkpoint passes. If booleans say the job isn't done, you'll be blocked.

Credentials exception: If missing (LOGFIRE_READ_TOKEN, TEST_EMAIL, TEST_PASSWORD), ask user once at start. Then proceed autonomously.

Completion Checkpoint

Before stopping, create .claude/completion-checkpoint.json:

{
  "self_report": {
    "is_job_complete": true,
    "code_changes_made": true,
    "linters_pass": true,
    "category": "bugfix"
  },
  "reflection": {
    "what_was_done": "Fixed CORS config, deployed, verified login works",
    "what_remains": "none",
    "key_insight": "Reusable lesson for future sessions (>50 chars)",
    "search_terms": ["cors", "deployment", "login"]
  },
  "evidence": {
    "urls_tested": ["https://staging.example.com/dashboard"],
    "console_clean": true
  }
}

Extra fields (evidence, urls_tested, etc.) are allowed — the stop-validator ignores unknown keys. If validation fails, the blocking message shows exact requirements.

Workflow

Phase 0: Pre-Flight Check

Create .claude/autonomous-state.json with "mode": "repair" at activation.

1. Read project documentation:
   • If QMD available: qmd_search "project architecture overview" — faster, semantic
   • If no QMD: Read docs/index.md and docs/TECHNICAL_OVERVIEW.md
2. Check for .claude/skills/appfix/references/service-topology.md
3. If missing: STOP and ask user for service URLs
4. Check credentials — ask user ONCE if missing

Phase 0.5: Codebase Context (First Iteration Only)

1. Call EnterPlanMode
2. FIRST: Temporal causality checkpoint
   • git log --oneline --since="48 hours ago" — What changed recently?
   • Does symptom timing correlate with any recent change?
   • If correlation exists → that change is your primary hypothesis
3. Explore: architecture, configs, error patterns
4. Write understanding to plan file
5. Call ExitPlanMode

Phase 0.75: Parallel Task Distribution

After ExitPlanMode, analyze plan for 2+ independent work items. Launch multiple Task tool calls in a SINGLE message for parallel execution. Each agent needs full context (file paths, errors, requirements).

Phase 1: Health Check

Check each service from service-topology.md:

curl -sf https://[service-url]/health || echo "UNHEALTHY"

Phase 2: Log Collection

• Azure: az containerapp logs show --name [app] --resource-group [rg] --type console --tail 100
• LogFire: curl -H "Authorization: Bearer $LOGFIRE_READ_TOKEN" "https://logfire-api.pydantic.dev/v1/query?level=error&since=1h"
• Browser: Chrome MCP read_console_messages

Phase 3: Execute Fix

1. Apply code changes with Edit tool
2. Commit and push: git add <files> && git commit -m "appfix: [description]" && git push
3. Deploy: gh workflow run deploy.yml -f environment=staging && gh run watch --exit-status
4. Health poll: for i in {1..12}; do curl -sf "$HEALTH_URL" && break || sleep 5; done

Phase 3.5: Linter Verification (MANDATORY)

Auto-detect and run ALL linters:

[ -f package.json ] && npm run lint
[ -f tsconfig.json ] && npx tsc --noEmit
[ -f pyproject.toml ] && ruff check --fix .

Fix ALL errors including pre-existing ones. No exceptions: "not my code" is prohibited.

Phase 3.6: Infrastructure Sync (if az CLI used)

Phase 3.7: Fix Validation Tests (MANDATORY for code changes)

Ask: "What would PROVE this specific fix worked?" Web smoke tests prove "the app loads" but NOT "the fix worked."

1. Define tests in checkpoint validation_tests.tests array
2. Execute tests, record actual results
3. If tests FAIL → fix root cause → re-run
4. Save artifacts to .claude/validation-tests/summary.json

Phase 4: Browser Verification (MANDATORY)

Use Surf CLI first, Chrome MCP only as fallback.

python3 ~/.claude/hooks/surf-verify.py --urls "https://staging.example.com/dashboard"
cat .claude/web-smoke/summary.json  # Must show passed: true

Artifacts in .claude/web-smoke/ are validated by the stop hook. If passed: false, you're blocked until issues are fixed.

Phase 4.2: Console Check

• ZERO uncaught JavaScript errors
• ZERO network requests returning 500
• Data actually displays (not spinner/loading state)

State File

.claude/autonomous-state.json tracks iteration state (created at activation with "mode": "repair"):

Environment Variables

Safety Gate (Production Only)

Pause for human confirmation ONLY for:

• Production environment targeting
• Destructive operations (delete, drop, truncate)
• Secrets exposure

All other actions proceed autonomously.

Exit Conditions

Skill Fluidity

You may use techniques from any skill for sub-problems without switching modes. Your autonomous state and checkpoint remain governed by /appfix.

Reference Files