azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

syncro skill: timer-entry-first workflow + heredoc payloads

Browse Source 
- 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>
This commit is contained in:
Howard Enos
2026-05-01 10:58:20 -07:00
parent 4f4491e7da
commit ec98c6c636
3 changed files with 235 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.claude/memory/MEMORY.md
View File

@@ -31,6 +31,7 @@
- [1Password — always use service token](feedback_1password_service_token.md) — Source OP_SERVICE_ACCOUNT_TOKEN from SOPS for every `op` call. Desktop-app integration prompts are unacceptable in agent flows.
- [/tmp path mismatch on Windows](feedback_tmp_path_windows.md) — Write tool and Git Bash resolve `/tmp` to DIFFERENT real dirs. Use heredoc or workspace path for JSON payloads handed to curl. Caused wrong-comment incident on Syncro #32225.
- [Syncro — never set contact on Cascades tickets](feedback_syncro_cascades_contact.md) — Cascades tickets must have `contact_id` blank; Syncro routes to the correct email distribution that way. Setting contact (often defaults to Meredith) overrides and breaks notifications. Never include the contact field in create or edit payloads for Cascades.
- [Syncro — log time entries first, never bare add_line_item](feedback_syncro_timer_first.md) — All Syncro work-time billing MUST go through `timer_entry → charge_timer_entry`. Bare `add_line_item` leaves Syncro time tracking at 00:00:00 and breaks reporting. Mike caught this on 2026-04-30 across 31 tickets; I repeated the bug on 2026-05-01 across 3 more.
## Machine
- [ACG-5070 Workstation Setup](reference_workstation_setup.md) - Windows 11 Pro clean install 2026-03-30, replaced CachyOS. All tools installed.

31
.claude/memory/feedback_syncro_timer_first.md Normal file
View File

@@ -0,0 +1,31 @@
---
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.