backend-debugging

name	backend-debugging
description	Systematic debugging for Encore.ts backend incidents using diagnostic scripts, database queries, and structured logging. Use when backend tests fail, services crash, or async flows stall.

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