Developer Handover Pack

Developer Handover Pack

Time Tracking and Billable Hours

Captures time entries from calendars and work tools and assembles draft timesheets per team member at the start of each period close. Replaces the manual step of reminding staff to log time (Step 1). Targets Karbon as the primary data source and writes draft entries back to the timesheet layer ready for gap detection.

// Input
karbon.period_close_event {
  period_start: ISO8601,
  period_end:   ISO8601,
  team_members: [ { id, name, karbon_user_id } ]
}

// Processing
FOR each team_member:
  fetch karbon.time_entries(user_id, period_start, period_end)
  fetch calendar.events(user_id, period_start, period_end)
  merge_and_deduplicate(entries, events)
  map_to_job_codes(merged) -> draft_rows[]
  flag_unresolved(draft_rows where job_code == null)

// Output
draft_timesheets[] {
  member_id:    string,
  period:       ISO8601 range,
  draft_rows:   [ { date, duration_mins, job_code, description, status } ],
  gap_flags:    [ { date, expected_hrs, logged_hrs, delta_hrs } ],
  confidence:   float  // 0.0 - 1.0
}

Identifies team members with missing or thin timesheet entries and sends targeted, specific nudges only to those individuals. Replaces both the manual email chase (Step 2) and the fill-from-memory step (Step 3). Nudges include the exact dates and expected hours that are missing, removing the need for the recipient to guess.

// Input
draft_timesheets[].gap_flags {
  member_id:    string,
  date:         ISO8601,
  expected_hrs: float,
  logged_hrs:   float,
  delta_hrs:    float
}

// Processing
FOR each gap_flag:
  resolve_channel(member_id) -> 'slack' | 'gmail'
  compose_nudge_message(member_id, gap_dates, delta_hrs)
  send_via_channel(channel, message)
  record_nudge_sent(member_id, timestamp, channel)
  IF nudge_count(member_id, period) > 2:
    escalate_to_practice_manager(member_id, gap_summary)

// Output
nudge_log[] {
  member_id:      string,
  channel:        'slack' | 'gmail',
  message_ref:    string,
  sent_at:        ISO8601,
  gap_dates:      [ ISO8601 ],
  escalated:      boolean
}

Matches captured and gap-closed timesheet entries to jobs and clients in Karbon, calculates billable totals, and prepares a reconciled hours package for partner approval. Once approved, exports confirmed hours to Xero for invoicing. Replaces the manual reconciliation step (Step 4) and the billing export step (Step 6). Step 5 (partner approval) remains a human gate and is not automated.

// Input
draft_timesheets[].draft_rows {
  member_id:    string,
  date:         ISO8601,
  duration_mins: integer,
  job_code:     string | null,
  description:  string,
  status:       'draft' | 'gap_filled'
}

// Processing
FOR each draft_row:
  match = karbon.jobs.lookup(job_code) OR fuzzy_match(client_name)
  IF match.confidence < 0.80: flag_for_review(draft_row)
  ELSE: assign(draft_row, match.job_id, match.client_id)
aggregate_by_job_and_client(matched_rows) -> billing_summary
post_for_approval(billing_summary) -> AWAIT partner_approval_signal
ON approval:
  xero.invoices.create(billing_summary) -> xero_invoice_ref

// Output
reconciliation_result {
  period:          ISO8601 range,
  matched_rows:    integer,
  flagged_rows:    integer,
  total_billable_hrs: float,
  billing_summary: [ { job_id, client_id, hrs, amount_usd } ],
  xero_invoice_ref: string | null,
  exported_at:     ISO8601 | null
}

// ─────────────────────────────────────────────────────────────────
// TRIGGER
// ─────────────────────────────────────────────────────────────────
CRON: every Friday 17:00 (or Karbon webhook: period.closing)
  -> emit: period_close_event { period_start, period_end, team_members[] }

// ─────────────────────────────────────────────────────────────────
// STAGE 1: TIME CAPTURE AGENT
// ─────────────────────────────────────────────────────────────────
period_close_event
  -> karbon.GET /time-entries?user={id}&from={period_start}&to={period_end}
  -> calendar.GET /events?user={id}&from={period_start}&to={period_end}
  -> merge_deduplicate(time_entries, calendar_events)
  -> map_job_codes(merged)  // confidence threshold: 0.80
  -> write: draft_timesheets[]
  -> evaluate: gap_flags[] = rows where logged_hrs < expected_hrs

// ─────────────────────────────────────────────────────────────────
// DECISION: GAPS FOUND?
// ─────────────────────────────────────────────────────────────────
IF gap_flags.length > 0:
  -> STAGE 2 (Gap Chaser Agent)
ELSE:
  -> STAGE 3 (Reconciliation Agent)

// ─────────────────────────────────────────────────────────────────
// STAGE 2: GAP CHASER AGENT
// ─────────────────────────────────────────────────────────────────
gap_flags[]
  -> FOR each member_with_gaps:
       resolve_channel(member_id) -> 'slack' | 'gmail'
       IF slack:
         slack.POST /chat.postMessage { channel: member.slack_id, text: nudge_msg }
       IF gmail:
         gmail.POST /messages/send { to: member.email, body: nudge_msg }
       record nudge_log { member_id, channel, sent_at, gap_dates, delta_hrs }
       IF nudge_count(member_id, period) > 2:
         notify practice_manager via Slack (escalation)
  -> AWAIT: timesheet updates OR nudge_window_expiry (48 hrs)
  -> re-evaluate gap_flags[]
  -> proceed: draft_timesheets[] (updated)

// ─────────────────────────────────────────────────────────────────
// STAGE 3: RECONCILIATION AGENT
// ─────────────────────────────────────────────────────────────────
draft_timesheets[]
  -> FOR each draft_row:
       karbon.GET /jobs?code={job_code}  // primary lookup
       IF no match: fuzzy_match(client_name, karbon.clients[])
       IF match.confidence < 0.80: flag_for_review -> notify practice_manager
       ELSE: assign { job_id, client_id, billable_hrs, billable_amount }
  -> aggregate: billing_summary { per_job, per_client, total_hrs, total_amount }
  -> notify partner: review summary (Slack or email)

// ─────────────────────────────────────────────────────────────────
// HUMAN GATE: PARTNER APPROVAL (Step 5, retained)
// ─────────────────────────────────────────────────────────────────
  -> AWAIT: partner_approval_signal { approved: boolean, notes: string }
  IF approved == false: return billing_summary to practice_manager for correction
  IF approved == true:  proceed to export

// ─────────────────────────────────────────────────────────────────
// EXPORT: XERO BILLING
// ─────────────────────────────────────────────────────────────────
billing_summary (approved)
  -> xero.POST /api.xro/2.0/Invoices {
       Type: 'ACCREC',
       Contact: { ContactID: client.xero_contact_id },
       LineItems: [ { Description, Quantity: hrs, UnitAmount, AccountCode } ],
       Status: 'DRAFT'
     }
  -> store: xero_invoice_ref, exported_at

// ─────────────────────────────────────────────────────────────────
// OUTPUT
// ─────────────────────────────────────────────────────────────────
reconciliation_result {
  period, matched_rows, flagged_rows,
  total_billable_hrs, billing_summary[],
  xero_invoice_ref, exported_at
}
// Pipeline complete. Hours exported to Xero as draft invoices.