Ticket HR-PAY-01: explain a take-home change after a work-state move
One of the build tickets the firm's team received on day 10, with its test cases and the scorecard that decides the next round of funding. A representative ticket; names, wording and figures changed.
The prototype answered the most common payslip question with a confident, wrong explanation.
| Employee asked | Prototype answered (day 6) | Payroll's approved answer |
|---|---|---|
| "My take-home dropped $166 this pay. I moved from the Dallas client to the Chicago one on the 14th. Why?" | "Changes in take-home pay are usually caused by changes to your federal withholding (W-4) or benefit deductions. Please check your W-4 elections." | "Your work state changed from Texas to Illinois on the 14th. Texas has no state income tax; Illinois withholds 4.95%. 8 of the 11 working days this period were in Illinois, so $166 of Illinois tax was withheld. A full Illinois period will be about $228." |
Root cause: the prototype could not see the work-location history or per-state tax lines in ADP, so the model filled the gap with a generic answer. No figure was wrong, but the explanation was. 6 of the 24 prototype misses had this cause.
Map the ADP data an explanation needs, compute it in code, and hand anything incomplete to payroll.
- Read from ADP (read-only, signed-in employee only): work-location history with effective dates; tax lines by jurisdiction for the current and previous period; earnings codes, including retro pay; pay period dates.
- Compute the change in code: compare the two periods line by line and attribute the difference to state tax, retro pay, deductions or hours. The model only words the explanation.
- If any required field is missing or the difference cannot be fully attributed, do not answer: open a payroll ticket with the employee's question and the two periods attached.
Out of scope: local taxes, multi-state reciprocity rules beyond the 14 states on file, and any change to pay records.
Depends on: ADP API sandbox access (IT director, week 1); 40 approved answers from payroll for the test set (payroll lead, week 4).
The ticket is done when all of these pass on masked production data.
| ID | Situation | Expected behaviour |
|---|---|---|
| T1 | Mid-period move from a no-tax state to a taxed state | Explains the new state tax with the exact amount from ADP; days split matches payroll |
| T2 | Retro pay for a rate change paid this period | Names the retro amount and the periods it covers |
| T3 | Move and retro pay in the same period | Attributes both; the parts add up to the total change, to the cent |
| T4 | Work-location record missing an effective date | No answer given; payroll ticket opened with both periods attached |
| T5 | Employee asks about a colleague's pay | Refused; attempt logged |
| T6 | Difference cannot be fully explained by mapped fields | No partial answer; routed to payroll |
Pass rule: every figure shown matches ADP exactly; any unexplained difference goes to payroll. Each test is added to the 300-question release set.
The pilot result decides whether the remaining $33,000 is released.
| Measure | Prototype, day 6 (observed) | Week 14 target | If missed |
|---|---|---|---|
| Covered questions answered correctly | 92% | 95% | Hold rollout until fixed |
| Wrong pay figures | 0 of 300 | 0 | Stop; no release |
| Answered without HR (72-hour rule) | not measurable | 70% | Recompute payback; apply stop rule |
| Pilot consultants using it | n/a | 60% of 150 | Fix launch channel before rollout |
The pilot measures pay and policy questions directly. Leave is estimated from the prototype; salary advances are estimated from the written rules. If all four targets are met and run-rate payback is 18 months or less, the committee releases the remaining $33,000 for leave and advances. Between 18 and 24 months, leave goes ahead and advances wait.