| name | debugging-operations |
| description | Diagnose TMET runtime, queue, scraping, upload, and file-artifact issues. Use when investigating failing routes, stuck jobs, broken Browserless/SUAP flows, malformed CSV or JSON outputs, Docker problems, or test regressions. |
Debugging and Operations (TMET)
Use this skill to
- Triage backend failures in
routes/, models/, and helpers/.
- Investigate queue lifecycle issues in
helpers/queue.js and /api/jobs/:jobId.
- Diagnose broken pipeline artifacts in
files/*.json and files/*.csv.
Fast triage flow
- Reproduce with the smallest route call, test file, or model method that still shows the problem.
- Check
docker compose logs -f node and the closest failing test.
- Confirm queue state through
/api/jobs/:jobId when the bug involves async work.
- Inspect the specific generated file involved instead of assuming the wrong stage failed.
- Verify environment variables only for the integrations that the failing flow actually touches.
Common hotspots
helpers/scraper.js + config/suap-config.js for SUAP login/session issues
helpers/timetables.js for EduPage extraction issues
helpers/moodle-uploader.js for Moodle upload failures
helpers/chat-assist.js + models/AIMatch.js for AI matching failures
helpers/queue.js when jobs appear stuck, missing, or prematurely cleaned up
Commands
docker compose ps
docker compose logs -f node
docker compose exec node npm test -- tests/routes/suapRoute.test.js
docker compose exec node npm test -- tests/helpers/queue.test.js
Out of scope
- Incident tooling outside this repository.
- Message brokers, worker pools, or persisted job systems that TMET does not implement.