SKILL.md

skills/bitrix-tracker/SKILL.md

1. ---
2. name: bitrix-tracker
3. description: >-
4. Generate a read-only status digest of Bitrix24 tasks so nothing slips through the cracks. Pulls
5. tasks via the Bitrix REST API and groups them into what needs attention (overdue, unassigned,
6. stale with no movement in N days, and changed since yesterday), then prints a clean digest. Use
7. when someone wants to "track" Bitrix work, get a daily or morning status of the task queue, see
8. what's overdue or unassigned, find tasks that have gone quiet, or stop manually scrolling Bitrix
9. to keep tabs on things. It is read-only and never changes a task. Built for Hazel's tracking
10. request; the buckets are configurable.
11. ---
13. # Bitrix Tracker
15. A read-only status digest of the Bitrix24 task queue. It answers "what needs attention right now?" without anyone scrolling the CRM.
17. ## What it does
19. Reads tasks from Bitrix24 via an inbound webhook and sorts them into attention buckets:
21. - **Overdue**: deadline is in the past and the task isn't closed.
22. - **Unassigned**: no real responsible person (responsible is empty or matches the configured "unassigned" placeholder).
23. - **Stale**: no change in the last N days (default 7) and still open.
24. - **Changed since yesterday**: moved in the last 24 hours (useful as a "what happened" glance).
26. It only reads. It never edits, assigns, or closes anything, so there's no write-gate and no risk of it touching live data.
28. ## Setup
30. 1. Copy `config.example.json` to `config.json` and adjust:
31. - `stale_days`: how many days of no movement counts as stale (default 7).
32. - `unassigned_ids`: Bitrix user IDs (or empty value) that mean "nobody really owns this." Often the account owner's ID if your team uses that as a holding pen.
33. - `task_filter`: which tasks to pull (default: open, not closed).
34. 2. Copy `.env.example` to `.env` and set `BITRIX_WEBHOOK_URL` (the `https://<domain>.bitrix24.com/rest/<user_id>/<token>/` base URL). Needs **task** read scope. If you later want deals tracked too, the same webhook needs CRM scope and we add a deals bucket.
36. The webhook URL is a credential. Treat `.env` like a password; don't commit it.
38. ## Running it
40. ```bash
41. python scripts/bitrix_tracker.py # digest from live Bitrix
42. python scripts/bitrix_tracker.py --mock # digest from bundled sample_tasks.json
43. python scripts/bitrix_tracker.py --json # machine-readable output instead of text
44. ```
46. ## Output
48. A dated digest with a one-line count per bucket, then the tasks under each (ID, title, owner, and the relevant date: deadline for overdue, last-change for stale). Empty buckets are shown as "clear" so a quiet day reads as reassurance, not a blank screen.
50. ## Tuning the buckets
52. The four buckets are a sensible default for "tracking," but a reader may want something narrower (their own open tasks, one project group, deals rather than tasks). The buckets and filter live in `config.json`, so reshaping the digest doesn't mean touching code. Keep the buckets people act on and trim the rest.
54. ## Going automatic
56. This pairs naturally with a scheduled task, e.g. run every weekday at 8am and drop the digest somewhere the team will see it. Since it's read-only, scheduling it carries no risk; it's just a question of where the output should land (email, a doc, a chat message).
58. ## How to read failures
60. - `BITRIX_WEBHOOK_URL not set` → `.env` missing or empty.
61. - HTTP 401 / "Invalid token" → webhook URL wrong or revoked.
62. - Empty digest with a live connection → check `task_filter`; the default only pulls open tasks.