Howard Enos
ec98c6c636
- Promote timer_entry → charge_timer_entry to default billing path; demote bare add_line_item to a clearly-labeled fallback for non-time items only. Mike caught the bare-add_line_item bug across 31 tickets on 2026-04-30; repeated on 3 tickets 2026-05-01. Time entries are required for Syncro reporting (hours per client, tech productivity, prepay burn). - Replace /tmp/*.json payload pattern with heredoc throughout. /tmp resolves to C:\tmp\ in the Write tool but %LOCALAPPDATA%\Temp\ in Git Bash on Windows — different real directories. Caused a wrong-comment incident on ticket #32225 2026-05-01 (rogue payload from prior session). Heredoc avoids the file handoff entirely. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
32 lines
3.2 KiB
Markdown
32 lines
3.2 KiB
Markdown
---
|
|
name: Syncro — log time entries first, never bare add_line_item
|
|
description: All Syncro tickets must have a Syncro time entry recorded for any work done. Use timer_entry + charge_timer_entry to bill, NOT bare add_line_item. Bare add_line_item leaves Syncro time tracking at 00:00:00 and breaks reporting (hours per client, tech productivity, prepay burn rate). This applies even to warranty/free work; only cancelled tickets are exempt.
|
|
type: feedback
|
|
---
|
|
|
|
**Rule:** When billing a Syncro ticket, the workflow MUST be:
|
|
|
|
1. Do the work.
|
|
2. POST `/tickets/{id}/timer_entry` with `start_at`, `end_at`, `billable`, `product_id`, `notes`. This records hours in Syncro's time-tracking system.
|
|
3. POST `/tickets/{id}/charge_timer_entry` with `{"timer_entry_id": N}` to convert the timer into a billable line item on the ticket.
|
|
4. POST `/invoices` to roll the line item onto a customer invoice.
|
|
5. PUT ticket status as needed.
|
|
|
|
**Why:** Syncro's reporting (hours per client, technician productivity, average resolution time, prepay burn rates) is built on the **time-entries** table, not on invoice line items. If we use bare `add_line_item` and type hours into the description ("Applied 1.5 Prepay Hours"), the invoice posts but Syncro's time tracking shows `00:00:00`. We lose all reporting visibility on actual work performed.
|
|
|
|
**How to apply:**
|
|
|
|
- **Default billing path:** `timer_entry → charge_timer_entry → invoice`. Always.
|
|
- **Bare `add_line_item` is NOT a default option.** Only acceptable when there is genuinely no time component to bill — e.g. selling a hardware product or a flat-fee service with zero labor. For any work-time billing, use the timer path.
|
|
- **Even warranty/free work needs a time entry.** Set `billable: false` (or appropriate type) on the timer entry. Time still records, just doesn't generate a paid line item.
|
|
- **Only cancelled tickets are exempt** from time entries.
|
|
|
|
**Real-world incident — 2026-04-30:** Mike audited 31 closed tickets and found ALL 31 had `00:00:00` in Syncro time tracking. 29 had proper invoices with revenue captured correctly, but the underlying time data was bypassed entirely. Examples: #32156 (Cascades) "Applied 8.0 Prepay Hours" — should have been an 8.0 hr time entry. #32218 (Instrumental) "Applied 1.5 Prepay Hours" — should have been a 1.5 hr time entry.
|
|
|
|
**Repeat incident — 2026-05-01:** I (Claude, Howard's session) billed three tickets the same broken way (#32225 Sombra $525, #32229 Mineralogical Record $262.50, #32214 Cascades $0 prepaid). Winter retroactively added time entries to fix them. The skill examples need to be updated to make timer-first the default, and that's tracked in the syncro skill rewrite work.
|
|
|
|
**Where the fix needs to land:**
|
|
- `.claude/commands/syncro.md` — promote the timer-entry workflow to be the documented default. Demote `add_line_item` to a clearly-labeled fallback for non-time work only. Every example in the "Billing workflow" section should use the timer path.
|
|
|
|
**Skill author note:** Currently the skill presents both patterns as Option A (simpler — add_line_item) and Option B (timer + charge). That framing is wrong. Option B is the only correct path for time-bearing work; Option A is a fallback at best.
|