Payroll Prep

Get the hours right before anyone gets paid.

Payroll is the finance workflow with the least room for error. A wrong invoice gets corrected next week. A wrong paycheck is a person who cannot cover rent, and it is the fastest way for an owner to lose a crew. Everything in this skill is built around that asymmetry: the machine assembles and checks, the owner decides.

Step 1 — Fix the period before anything else

Confirm the pay period start and end dates, the pay date, and who is in this run. Getting the period wrong duplicates or skips a week of someone's pay, and it is a surprisingly easy mistake when a period straddles a month end.

Confirm the roster too: new hires who started mid-period, anyone terminated, anyone on leave. See reference/timesheet_intake.md.

Step 2 — Pull the timesheets

With Gusto connected, first ask Gusto itself what stands in the way: call its payroll-blockers check (list_payroll_blockers) before building anything. If blockers come back, translate each into plain English — what it means, who fixes it, and where. For example: "check payments unsupported" means this company pays by paper check, which the integration cannot stage, so the owner runs that part in Gusto directly; "bank account not connected via Plaid" means the owner connects the bank in Gusto's settings; "hourly employees unsupported" can block at the account level even when this run is salaried-only. Blockers are a routing signal, not a failure — the run still gets built and validated here, and the deliverable becomes the run sheet with the blocker list riding along.

Then pull the period's inputs, each from its own tool. Hours: list_time_records for the pay period; read its source field before anything else. native returns shifts with clock-in, clock-out, and breaks; third_party returns timesheets from the company's time-tracking partner, and get_time_sheet gives the per-day line items for any one of them (it refuses native shift ids); none means Gusto holds no hours for this company, so the spreadsheet path below supplies them. Leave: list_time_off_requests for the period with status: approved — every approved day is paid as PTO or sick, never as worked, and a pending request is a flag, not a paid day. Balances: get_time_off_balances, which is what the "PTO beyond available balance" check in Step 4 reads against. Rates and classifications: the roster from list_employees with each person's compensations. Rates come from Gusto, never from a timesheet. Call shapes for these are in ../../shared/connector-call-shapes.md.

A missing punch the owner can fill. When Step 4 flags a shift with no clock-out and the owner gives the real times, record_time writes them — only the times the owner stated, shown to them first, and as an update of the existing shift rather than a second entry. The parameters that refuse if missing (timezone, job on Gusto's own tracking, which id counts as the shift) and the one re-read trap (a contractor's confirmed hours come back with blank clock times; do not write again) are in the record_time row of ../../shared/connector-call-shapes.md. Read that row before the call. This is the only way the skill ever changes a punch; an assumed time is never written.