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 analysisreferences/diagnostic-scripts.md – CLI usage notes for inspect-run.ts, check-agent-state.ts, check-cursor-ordering.ts, and friendsreferences/common-failures.md – Symptom → cause → fix catalogue for top regressionsreferences/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 regressionse2e-testing_skill – Playwright coverage for verifying frontend/backends flows end-to-endgraphiti-mcp-usage_skill – Capture debugging RCA and permanent fixes in the knowledge graph
1---2name: backend-debugging3description: 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.4---5
6# Backend Debugging Skill
7
8## Mission
9Restore 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.
10
11## When to Use
12- `encore test` failures or flaky integration tests
13- Stalled workers (runs stuck `queued`/`in_progress`)
14- Graph projector or subscription issues
15- CI regressions surfaced by `task backend:test` or smoke suites
16
17## Rapid Response Workflow
181. **Reproduce & capture context** – Re-run the failing test with `encore test …` and collect assertion + log data.
192. **Inspect database state** – Use targeted queries from `references/debug-queries.md` to confirm run status, events, and projector outcomes.
203. **Run diagnostic scripts** – Leverage the tools catalogued in `references/diagnostic-scripts.md` to inspect timelines, cursors, and agent snapshots.
214. **Apply fix & verify** – Update code, rerun tests, and document the outcome in Graphiti (include root cause + remediation).
22
23## Triage Aids
24- `references/common-failures.md` – Symptom ➜ cause ➜ fix matrix for the most frequent issues (queued runs, hanging services, alias errors, projector lag, budget exhaustion).
25- `references/detailed-examples.md` – Step-by-step walkthroughs, including the "0 screens discovered" scenario and RCA templates.
26
27## Debugging Checklist
28- Worker claimed the run (status not `queued`)
29- Subscription imports present in test file
30- Run completed (`status = 'completed'`)
31- Events emitted and projector outcomes present
32- Async processing given time to complete (polling, not sleeps)
33- Appium/device online when required
34- Structured logs inspected for module/actor context
35
36## Critical Rules
37- **Structured Logging:** Use `encore.dev/log` with `module`, `actor`, and identifiers (`runId`).
38- **Subscriptions:** Import every PubSub worker in tests before publishing events.
39- **Polling:** Prefer polling loops with timeouts over fixed `setTimeout` sleeps.
40
41## Reference Library
42- `references/debug-queries.md` – SQL snippets for runs, events, projector state, and lag analysis
43- `references/diagnostic-scripts.md` – CLI usage notes for `inspect-run.ts`, `check-agent-state.ts`, `check-cursor-ordering.ts`, and friends
44- `references/common-failures.md` – Symptom → cause → fix catalogue for top regressions
45- `references/detailed-examples.md` – Expanded case studies (e.g., projector lag, budget exhaustion)
46
47## Testing in CI/CD
48```yaml
49# .github/workflows/test.yml
50- name: Run backend tests
51 run: |
52 cd backend
53 encore test
54```
55**Prerequisites:** Appium + device available for integration suites, environment variables configured, Run logs streamed via `task backend:logs` when debugging CI.
56
57## Related Skills
58- `backend-development_skill` – Integration-first testing patterns that prevent regressions
59- `e2e-testing_skill` – Playwright coverage for verifying frontend/backends flows end-to-end
60- `graphiti-mcp-usage_skill` – Capture debugging RCA and permanent fixes in the knowledge graph
majiayu000