| 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 thing |
|---|
| ats | crud | crowded market — needs a sharp angle, not "another tracker" | configurable-per-req pipeline stages + structured scorecards; don't ship a generic Kanban |
| onboarding | crud | the offer→onboard data-carry gap incumbents admit is unsolved | carry candidate data forward with zero re-entry; I-9 tasks with 3-day deadlines |
| workforce-scheduling | booking | shift scheduling for hourly teams | coverage rules + overtime + swap/coverage approval, not a bare calendar |
| engagement | crm | engagement surveys for SMB | eNPS as the headline metric; anonymity threshold so small teams can't deanonymize responses |
onboarding is the differentiated bet (solve the admitted gap). ats is the crowded one
— architect must name the sharp angle in the ARCH doc or it's dead on arrival.
6. Compliance (light)
Flag these in the ARCH doc; route AI-screening to a reviewer.
- EEO / OFCCP — collect voluntary self-ID; aggregate reporting; never in the
decision path.
- I-9 / E-Verify — Section 1 by day one, Section 2 within 3 business days; model the
deadline.
- Anti-discrimination — disparate impact in screening. If any product uses AI to
screen/rank candidates, flag it to
hr-ai-reviewer (or the AI-security reviewer) before
senior-dev starts — automated screening is a high-risk surface.
- Ban-the-box — many jurisdictions forbid asking criminal history before an offer.
Don't put it on the application form by default.
- FLSA / overtime — scheduling must compute overtime for hourly workers; respect
fair-workweek / predictive-scheduling laws where they apply.
- Data retention — candidate/applicant records have minimum retention (e.g. EEOC
~1 year) and deletion obligations (GDPR/CCPA right-to-erasure). State a retention policy.
Output
When applied, contribute a Domain constraints block to the architecture doc:
## Domain constraints (HR/recruiting)
- pipeline: stages configurable per req (not a fixed enum)
- EEO data: segregated store, excluded from decision view
- offer→onboard: candidate data carried forward, zero re-entry
- I-9: Section 2 deadline = start + 3 business days (modeled)
- scheduling: coverage rule = <min staffed>, overtime flag, swap-approval
- AI screening: <none | flagged to hr-ai-reviewer>
- retention: <policy + jurisdiction>
Cross-references
- [[vertical-onboarding]] — the import-first onboarding funnel; the offer→onboard
data-carry here is the import that feeds first-run for the onboarding product.
- [[migration-ready-schema]] — model Candidate/Offer/Onboarding so data carries forward
cleanly (the no-re-entry wedge depends on it).
- [[lifecycle-messaging]] — candidate-stage and onboarding-task notifications (offer sent,
I-9 due, shift posted, survey open).
