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

•Reproduce & capture context – Re-run the failing test with encore test … and collect assertion + log data.
•Inspect database state – Use targeted queries from references/debug-queries.md to confirm run status, events, and projector outcomes.
•Run diagnostic scripts – Leverage the tools catalogued in references/diagnostic-scripts.md to inspect timelines, cursors, and agent snapshots.
•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

yaml

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