/vertical-hr-recruiting

name: vertical-hr-recruiting
description: Domain-knowledge primer for the HR & recruiting vertical (ATS, onboarding, workforce scheduling, engagement). Applied by architect/pm during spec authoring so they aren't naive about hiring pipelines, the admitted offer→onboard data-carry gap, EEO/I-9 compliance, and shift-coverage rules. Stops the four products from being specced as generic CRUD when the domain has hard legal and workflow constraints.
when_to_use: |
  Apply when:
  - architect writes ARCH-*.md for ats / onboarding / workforce-scheduling / engagement
  - pm decomposes any of these four products into tasks and needs domain entities
  - a spec touches candidates, requisitions, offers, I-9, shifts, or EEO data
  Do NOT apply for products outside the HR/recruiting vertical.
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"

Vertical: HR & recruiting — don't spec it naive

The incumbents (Workable, BambooHR, Greenhouse, Lever, Zoho Recruit, Manatal) have trained buyers to expect a hiring pipeline that *works*. A generic CRUD app fails the moment it meets EEO law, I-9 timing, or the offer→onboard handoff. **Read this before speccing any of the four products — the domain has hard constraints, not just forms.**

1. Domain vocabulary

• **ATS** — applicant tracking system; the system of record for hiring.
• **Requisition (req)** — an approved open role. Hiring happens *against a req*, not in a

vacuum. Reqs have an approval workflow (hiring manager → finance/HR).

• **Pipeline stages** — `applied → screen → interview → offer → hired` (plus `rejected` /

`withdrawn`). Stages are **configurable per req** — engineering and sales hire differently.

• **Candidate vs applicant** — an *applicant* applied to a specific req; a *candidate* is a

person in your talent pool who may map to many applications over time. Don't conflate them.

• **Sourcing** — proactively finding candidates (vs inbound applications).
• **Structured interview + scorecard** — pre-defined questions + a rubric each interviewer

scores. Reduces bias and legal exposure vs freeform notes.

• **Offer letter** — formal terms; triggers the offer→onboard transition on acceptance.
• **EEO data** — voluntary race/gender/veteran/disability self-ID, collected for

reporting, **segregated from hiring decisions** (see §2).

• **I-9 + E-Verify** — employment eligibility verification; **strict 3-day timing** (§2).
• **Onboarding checklist** — tasks a new hire/employer must complete before/at start.
• **time-to-hire / time-to-fill** — core recruiting metrics (hire = offer accepted by a

candidate; fill = req closed). Different denominators; report both correctly.

• **Hourly vs salaried** — drives scheduling, overtime (FLSA), and pay rules.
• **Shift swap / coverage** — hourly workers trade shifts; coverage rules say a slot can't

go unstaffed below a threshold.

• **eNPS** — employee Net Promoter Score; the headline engagement-survey metric.

2. Non-obvious domain rules

• **The offer→onboard handoff is the admitted gap.** Incumbents openly concede onboarding

is unsolved: data gets *re-entered* between the ATS and the HR/onboarding system. The whole onboarding product wedge is **carry the candidate's data forward — zero re-entry.**

• **EEO/OFCCP data must be collected but kept OUT of the hiring-decision view.** Mixing

self-identified race/gender into the screen/interview UI is an anti-discrimination liability. Store it segregated; surface it only in aggregate compliance reports.

• **Structured scorecards reduce bias and legal risk.** They create a defensible,

consistent record. Freeform-only interview notes are a disparate-impact landmine.

• **I-9 has strict timing**: Section 1 by the employee's first day, Section 2 (employer

review of documents) **within 3 business days of start.** Onboarding tasks tied to I-9 carry a hard deadline, not a soft reminder.

• **Workforce scheduling needs coverage rules + labor compliance.** A schedule isn't valid

just because slots are filled — it must respect minimum coverage, overtime (FLSA), predictive-scheduling / fair-workweek laws (advance-notice in some jurisdictions), and break rules.

• **Reqs gate hiring.** No offers without an approved req; req approval is a real workflow

with a budget/headcount check, not a checkbox.

3. What a naive build gets wrong

• **Hardcoded pipeline stages.** A fixed `applied→hired` enum breaks the first time a

customer wants a take-home or panel stage. Stages must be **configurable per req.**

• **EEO data in the candidate decision view.** Putting self-ID fields on the candidate card

the hiring manager sees is a legal-risk bug, not a UX choice. Segregate it.

• **Onboarding that re-enters candidate data.** Rebuilding name/email/role/comp from

scratch *is* the gap incumbents have. If onboarding starts from a blank form, you built the incumbent's weakness, not our wedge.

• **I-9 modeled as a generic checklist item.** Without the 3-business-day deadline and

Section 1 / Section 2 split, it's non-compliant.

• **Scheduling as a calendar.** Drag-and-drop shifts with no coverage minimum, no overtime

flag, and no swap-approval flow is a toy, not a workforce tool.

4. Must-model entities

| Entity | Must include | Why | |---|---|---| | **Requisition** | approval state, headcount, stage config | hiring is per-req; stages vary | | **Candidate** | stage history, scorecards, EEO (segregated store) | audit trail + bias defense; EEO must not leak into decision view | | **Offer → Onboarding** | carries candidate data forward (no re-entry) | this IS the wedge; the handoff is the gap | | **OnboardingTask** | deadline field (I-9 3-day timing) | compliance is time-bound, not soft | | **Shift** | coverage rules, overtime flag, swap/approval state | a schedule must be *valid*, not just full |

5. Per-product notes

| product | archetype | wedge | the one domain thin