Backend Debugging Skill

Mission

Restore failing Encore.ts flows quickly by combining structured logs, targeted SQL queries, and the diagnostic script arsenal. This skill keeps the top-level procedure concise; each reference file contains deep dive playbooks.

When to Use

• encore test failures or flaky integration tests
• Stalled workers (runs stuck queued/in_progress)
• Graph projector or subscription issues
• CI regressions surfaced by task backend:test or smoke suites

Rapid Response Workflow

1. Reproduce & capture context – Re-run the failing test with encore test … and collect assertion + log data.
2. Inspect database state – Use targeted queries from references/debug-queries.md to confirm run status, events, and projector outcomes.
3. Run diagnostic scripts – Leverage the tools catalogued in references/diagnostic-scripts.md to inspect timelines, cursors, and agent snapshots.
4. Apply fix & verify – Update code, rerun tests, and document the outcome in Graphiti (include root cause + remediation).

Triage Aids

• references/common-failures.md – Symptom ➜ cause ➜ fix matrix for the most frequent issues (queued runs, hanging services, alias errors, projector lag, budget exhaustion).
• references/detailed-examples.md – Step-by-step walkthroughs, including the "0 screens discovered" scenario and RCA templates.

Debugging Checklist

• Worker claimed the run (status not queued)
• Subscription imports present in test file
• Run completed (status = 'completed')
• Events emitted and projector outcomes present
• Async processing given time to complete (polling, not sleeps)
• Appium/device online when required
• Structured logs inspected for module/actor context

Critical Rules

• Structured Logging: Use encore.dev/log with module, actor, and identifiers (runId).
• Subscriptions: Import every PubSub worker in tests before publishing events.
• Polling: Prefer polling loops with timeouts over fixed setTimeout sleeps.

Reference Library

• references/debug-queries.md – SQL snippets for runs, events, projector state, and lag analysis
• references/diagnostic-scripts.md – CLI usage notes for inspect-run.ts, check-agent-state.ts, check-cursor-ordering.ts, and friends
• references/common-failures.md – Symptom → cause → fix catalogue for top regressions
• references/detailed-examples.md – Expanded case studies (e.g., projector lag, budget exhaustion)

Testing in CI/CD

# .github/workflows/test.yml
- name: Run backend tests
  run: |
    cd backend
    encore test

Prerequisites: Appium + device available for integration suites, environment variables configured, Run logs streamed via task backend:logs when debugging CI.

Related Skills

• backend-development_skill – Integration-first testing patterns that prevent regressions
• e2e-testing_skill – Playwright coverage for verifying frontend/backends flows end-to-end
• graphiti-mcp-usage_skill – Capture debugging RCA and permanent fixes in the knowledge graph