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

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