14.2 Writing the Requirements Spec

A working specification has two complementary parts. The Business Requirements Specification (BRS) captures what success looks like from the stakeholder’s point of view; the Data Specification captures what success looks like from the data’s point of view. Both are needed — one without the other is a recipe for rework.

14.2.1 The Business Requirements Specification

Translating Section 1’s discovery notes into the BRS template from Chapter 13 yields the following:

Project: Employee Absenteeism Predictive Analysis

Problem Statement: The HR department has observed increasing unplanned absence over the past two years but lacks insight into which factors drive high absenteeism or which employees are at risk. They need an evidence-based approach to target wellness interventions.

Key Questions:

  1. Which employee characteristics (demographic, health, work-related) are most strongly associated with chronic absenteeism?
  2. Can a model identify employees at risk of chronic absence (>40 hours/quarter) with at least 70% accuracy?
  3. How does absenteeism vary by season, day of week, and most common reason for absence?

Target Audience: HR managers who will use the results to design and target wellness programs. Results must be interpretable by non-technical stakeholders.

Deliverables:

  1. Exploratory analysis report with key visualizations (absenteeism by season, day of week, and employee characteristics).
  2. Logistic regression model predicting chronic absenteeism, with accuracy metrics on a held-out test set.
  3. Ranked risk list of current employees with predicted probability of chronic absence.
  4. One-page executive summary for senior leadership.

KPIs: Model accuracy >= 70%; the model must not use protected characteristics (gender, ethnicity, religion) as predictors; all deliverables completed within timeline.

Timeline: 2 weeks from data access. Interim check-in with HR at end of week 1.

Constraints: Data is limited to the past 3 years. Some employee records may have missing health data. The model must comply with company data ethics policy.

Notice that every line of this BRS is traceable to a specific question or response from Section 1. The “more than 40 hours per quarter” threshold did not come from the data — it came from a conversation. The exclusion of gender and ethnicity did not come from the modeling toolbox — it came from the company’s data ethics policy. A spec is the place where the analytical project meets the organization’s reality, and writing it forces those constraints into the open before they become surprises in the deliverables.

14.2.2 The Data Specification

The BRS describes what the project must produce; the data specification describes what the project must consume.

Data sources. The raw absence-event records from the Brazilian courier company (UCI Machine Learning Repository, July 2012 – July 2014), available at the book’s hosted dataset URL. The cleaned employee-level dataset from Chapter 6 is almost what we need — but Chapter 6 dropped the ID column because none of its downstream uses required it. Deliverable 3 of this project (the ranked risk list) does require ID, so the project will re-run the aggregation from the raw data with ID preserved. This is a recurring spec-driven pattern: a downstream stakeholder need can force an upstream change to the data pipeline, and the spec is what makes the need visible before the analyst is halfway through a model.

Required transformations. Aggregation from event-level to employee-level records, retaining ID, Service time, and Distance from Residence to Work (all needed as candidate predictors). One additional transformation specific to this project: a binary Chronic flag derived from the BRS definition — TRUE when an employee’s average quarterly absenteeism in the observation window exceeds 40 hours, FALSE otherwise. Section 4 documents the specific normalization choice.

Quality criteria. The four quality dimensions from Chapter 13 — completeness, accuracy, timeliness, consistency — translate into the following project-specific thresholds:

  • Completeness. No missing values in Age, Service time, Body mass index, or Reason for absence. Up to two missing values are tolerated in non-essential variables.
  • Accuracy. Age between 27 and 58; Body mass index between 19 and 38; Absenteeism time in hours between 0 and 120 per event.
  • Timeliness. All records dated within the past three years.
  • Consistency. Education levels in {high school, graduate, postgraduate, master and doctor}; reason codes in {0, 1, …, 28}.

Data dictionary. The table below documents the variables required by this project’s analysis and model. Column names retain their original spaces and are referenced with backticks throughout the code.

Table 14.1: Table 14.2: Data dictionary for the Employee Absenteeism Predictive Analysis project.
Variable Type Range / Values Description
ID Integer 1–36 Employee identifier (preserved for Deliverable 3)
Age Integer 27–58 Employee age in years
Body mass index Numeric 19.0–38.6 BMI in kg/m²
Education Factor 1–4 (high school → master and doctor) Highest education completed
Distance from Residence to Work Integer 5–52 Commute distance, kilometers
Service time Integer 1–29 Years employed at the company
Most common reason for absence Integer 0–28 (ICD code) Modal ICD reason across the employee’s absence events
Number of absence Integer 0–8 Total recorded absence events per employee
Absenteeism time in hours Integer 0–120 per event Total hours absent across all events for an employee
Chronic Logical TRUE / FALSE (derived: > 40 hr/quarter) Project-defined chronic-absenteeism flag

14.2.3 Acceptance Criteria

The KPIs in the BRS become a checklist of acceptance criteria. The project is “done” when, and only when, all of the following can be answered “yes”:

  1. Has every key question in the BRS been answered, with supporting analysis or visualization?
  2. Does the predictive model meet the 70% accuracy threshold on a held-out test set?
  3. Have protected characteristics been excluded from the model’s predictors?
  4. Is each deliverable in a format the stated audience can consume without further translation?
  5. Has the analyst documented every transformation and modeling choice so that another analyst could reproduce the result?

These criteria are not aspirational. Section 5 (“Validating Against Spec”) translates each one into executable R checks that the project’s build pipeline runs automatically before any deliverable is shipped.