Team (team-*)v1.3.1

team-time

Skills and tools for the TIME team — firefighter rotation playbook, APES payroll debugging, and Holiday Calendar Service issue diagnosis

by Tahir RazaView on GitHub ↗
personiotimefirefighterrotationplaybookdlqsloincidenttriagehandoverapespayrolldebuggingabsence-periodholidaycalendarhcspublic-holidayhistorization

team-time

Skills and tools for the TIME team — firefighter rotation playbook, APES payroll debugging, and Holiday Calendar Service issue diagnosis.

Installation

claude plugin install team-time@personio-claude-code-marketplace

What does this plugin do?

Two skill families:

  1. Firefighter rotation toolkit — a primary skill + five fan-out sub-skills covering everything an IC needs during their TIME FF rotation: framework, morning shift-start sweeps, DLQ inspection, Jira triage, end-of-rotation handover, and a background hourly watcher. Read-only and advisory; never sends Slack messages, transitions tickets, or executes Rundeck jobs.
  2. Issue-specific debugging — guided step-by-step workflows for APES payroll code derivation and Holiday Calendar Service (HCS) issues.

Firefighter rotation toolkit

firefighter-tm

Primary entry / routing index for a TIME FF rotation. Reads playbook.md (canonical responsibilities, channels, runbook actions, handover map) and routes into the right sub-skill.

What you need:

  • Membership of #cir_tm_ff (C05RSJYNWKY); @ff_tm mention works.
  • Zendesk read access (CX context).
  • Datadog notification profile + on-call rotation entry.
  • data-access CLI working.

Quick Start:

Just describe the situation — natural-language triggers route here:

I'm on FF this week
starting firefighter rotation
what do I do as FF

Example:

It's Tuesday morning, your first day on the TIME firefighter rotation. Type I'm on FF this week. The skill:

  1. Hands you the canonical playbook (playbook.md) for ~5 min reading.
  2. Walks the day-one access checklist.
  3. Runs firefighter-tm-shift-start to confirm nothing's on fire.
  4. Starts the hourly background watcher (firefighter-tm-watch start).
  5. Points you at the handover-note pattern so you capture the right context all week.

Why would you want this?

  • One discoverable entry point for the whole rotation — no hunting for the right wiki page.
  • Drift-resistant by design — workflow logic lives in the skill, specific values (queue names, SMEs, SLO IDs) are looked up live from dashboards / wiki / Slack at invocation time.
  • Captures runbook gaps as you go — the handover skill drafts Jira + Confluence artefacts so the next FF inherits less tribal knowledge.

firefighter-tm-shift-start

A once-a-morning status snapshot — seven parallel read-only checks (synthetics, SLOs, DLQs, cron health, PAT Jira, Slack intake, active incidents) plus a Tuesday-only read of the Time Management Operations Review Google Doc post-0930. Prints one short report.

What you need:

  • firefighter-tm setup complete (channel membership, Datadog access).
  • Slack MCP (claude.ai Slack) available for channel reads.
  • Datadog MCP (claude.ai Datadog) for SLO / DLQ / synthetic queries.

Quick Start:

morning FF check
start of FF shift
what's the state of things?

Example output (everything clean):

SYNTH:  0 failures last 60m | no alerts last 14h ✓
SLOs:   all within budget ✓
DLQ:    0 attendance-side queues with depth>0 ✓
CRON:   2 attendance jobs healthy ✓
JIRA:   1 new | 0 nearing SLO  → ATTPOL-1234 "title…"
SLACK:  0 unanswered @ff_tm | handover=no ✓
ACTIVE: none ✓

If something is dirty, the dirty line leads with ⚠ and the skill suggests which sub-skill to invoke next.

Why would you want this?

  • Catches drift between alerts — DLQ messages, SLO burn, and missed cron jobs are slow-burn signals; this surfaces them in 30 seconds.
  • Consistent format every morning — handover succession is cleaner when shift-start reports look the same week to week.

firefighter-tm-dlq-sweep

Inspects TIME-owned SQS dead-letter queue depths by reading the [prod] Time DLQs and Cron Jobs Datadog dashboard live (resolved by name via search_datadog_dashboards, never pinned by ID). Queue names, thresholds, and per-queue Rundeck-requeue URLs come from the dashboard widgets, not hardcoded — so the skill auto-tracks when the dashboard owners update it.

What you need:

  • Datadog MCP available.
  • Rundeck access for any requeue you intend to run (the skill never executes; the operator does).

Quick Start:

check DLQs
are there DLQ messages
TM DLQ

Example:

firefighter-tm-shift-start flagged a non-zero DLQ. Run the sweep:

check the DLQs

The skill:

  1. Reads the DLQ dashboard widget tree (queues per group + runbook notes).
  2. Classifies each group as attendance-side (you own) or handover (forward to the Absences team / HCS).
  3. Runs the dashboard's own depth + age metric queries.
  4. Samples recent worker errors via Datadog logs for each non-zero attendance-side queue.
  5. Proposes the action — requeue URL from the dashboard's adjacent runbook note, or "ping the Absences team via #cir_productdev_absences" for handover queues.

Applies operational heuristics not on the dashboard: time-balances DLQs are dark-mode (investigate, don't requeue blindly); APES recalc-queue growth is routine; working-models requeue uses a different Rundeck job.

Why would you want this?

  • Dashboard-led — the dashboard owners keep the queue list current; the skill rides on their maintenance instead of duplicating it.
  • TIME-scope filter — clearly separates "you own and fix this" from "you forward and ping the owning team".
  • 14-day retention SLA enforced — flags time-critical queues (age ≥ 10 d) before data loss.

firefighter-tm-jira-triage

Walks the PAT board for untriaged tickets, classifies each (valid? in TIME scope? Zendesk count? CX priority? FF handles or hand over?), and proposes a triage action per ticket. Read-only — drafts proposals; you apply them in Jira.

What you need:

  • Atlassian MCP available for JQL queries.
  • The responsibility map loaded mentally or accessible.

Quick Start:

triage the TM board
check TM Jira
PAT board triage

Why would you want this?

  • Consistent decision tree — the playbook's "FF handles vs hand over" rules applied uniformly.
  • Out-of-scope routing — handover targets surfaced for EO / payroll / EPD / etc.
  • SLO awareness — flags high-prio tickets idle for >2d, before they breach.

firefighter-tm-handover

End-of-rotation summary generator. Drafts a Slack-ready handover message for #cir_tm_ff plus a longer Confluence-format summary — never sends either. Captures runbook gaps as structured artefacts (one Jira draft + one Confluence-comment draft per gap).

What you need:

  • Read access to #cir_tm_ff (to pull the team's recent handover format).
  • Datadog + Jira MCPs for the 7-day signal pulls.

Quick Start:

firefighter handover
end of rotation summary
wrap up FF rotation

Why would you want this?

  • Inherited context — the next FF gets a structured note with open tickets, DLQ trend, incident summary, and SLO budget delta.
  • Runbook gaps converted to drafts — captures gaps you hit during the rotation as Jira ticket + Confluence comment drafts (operator reviews + posts).
  • Honours the standing don't-post-unprompted rule — the skill drafts; you decide what goes out.

firefighter-tm-watch

Hourly background watcher for the full rotation. Tracks SLO error-budget burn, TIME DLQ depths + ages, synthetic test failures, attendance cron health, PAT untriaged count, and (best-effort) Slack signals — unanswered @ff_tm pings on #cir_tm_ff plus unacked monitor alerts on #not_alerts_tm. Creates a Claude cron via CronCreate; remember to stop it at end of rotation.

What you need:

  • Datadog + Jira MCPs.
  • (Optional) Slack MCP — best-effort; skipped gracefully in cron contexts where the interactive auth isn't available.

Quick Start:

start ff watch
firefighter-tm-watch start

End of rotation:

firefighter-tm-watch stop

Why would you want this?

  • Catches slow-burn drift — DLQs growing, SLO budget eroding, cron silently broken — between the morning shift-start checks.
  • Hourly cadence, not minutes — designed to ride alongside Datadog monitors (the real-time alerting channel), not replace them.

Issue-specific debugging

/debug-payroll-derivation

Diagnose why an absence period has a wrong, missing, split, or stale payroll code.

What you need:

  • data-access plugin installed (claude plugin install data-access@personio-claude-code-marketplace)
  • One of: absence_period_id (preferred) or employee_id + company_id
  • A Jira ticket number for any queries that access PII (employee_attributes)

Quick Start:

/debug-payroll-derivation <absence_period_id> <company_id>

Example:

A customer reports they received payroll code 2.5 but expected 10.1 for a new hire on sick leave.

/debug-payroll-derivation 3f2a1b4c-... 42

The skill will:

  1. Fetch the currently assigned codes for the absence period
  2. Pull the stored derivation details and decision logs
  3. Route to the right scenario (wrong code, split, no code, stale)
  4. Walk through the attributes that influenced the result
  5. Pinpoint the root cause (e.g. hire_date outside the 28-day window) and suggest the fix

Why would you want this?

  • Unblock customers faster — diagnose payroll code issues independently without waiting for an APES service expert
  • No guesswork — follows the same decision tree APES uses, surfacing the exact attributes and logs that drove the result
  • Covers all failure modes — wrong code, split codes, no code (critical error or missing attributes), and stale derivations after a data fix
  • Safe by default — PII queries require a Jira ticket; read-only access only

/debug-holiday-calendar-issue

Diagnose and fix Holiday Calendar Service (HCS) issues — missing holidays, wrong absence durations, and incorrect system calendar data.

What you need:

  • data-access plugin installed (claude plugin install data-access@personio-claude-code-marketplace)
  • Company ID and Employee ID (for employee-specific issues)
  • A Jira ticket number

Quick Start:

/debug-holiday-calendar-issue company_id=12345 employee_id=67890

Or use the short alias:

/hcs TM-9999 company 12345

Example:

A customer reports that an employee in Munich is missing Bavarian public holidays in their Time off calendar.

/debug-holiday-calendar-issue TM-9999 company_id=12345 employee_id=67890

The skill will:

  1. Run the assignment endpoint to check which calendar is assigned and why
  2. Classify the issue (missing holidays, wrong duration, or wrong calendar data)
  3. Check historization mode and identify false positives
  4. Walk through the diagnosis for the specific issue type
  5. Recommend the exact fix — whether that's a CX template response, a Rundeck job, or an escalation

Why would you want this?

  • Covers 90% of holiday tickets — most are historization false positives that the assignment endpoint reveals immediately
  • Three issue types, one skill — wrong/missing holidays (Type 1), wrong absence duration (Type 2), and wrong system calendar data (Type 3)
  • Includes CX templates — copy-paste responses for the most common false positive scenarios
  • Rundeck guidance — exact job links and parameters for republishing events, switching historization mode, and syncing calendars