workforce_planning v1.0.0

name: "workforce_planning" description: "Workforce planning for a growing team: forecast demand by role from workload drivers, project supply with separate attrition, retirement, and transfer flows, run gap analysis by quantity, skill, timing, and cost, and build a sequenced hiring plan across base, growth, and squeeze scenarios with a runnable calculator. Use when asked for a workforce plan, headcount plan, hiring plan, staffing forecast, demand and supply analysis, or how many people to hire and when."

Workforce Planning

Purpose

Turn a business plan into a hiring plan that survives contact with reality. This skill builds the three tables every workforce plan needs (demand by role, supply after exits and internal moves, and the gap between them), splits hires into replacement and growth, works out when recruiting must start for people to be productive on time, and tests the whole plan under more than one future. A headcount total with no flow model, no start dates, and one scenario will fail as soon as the first person leaves.

Workflow

1. Fix the scope before any numbers. Planning unit (whole company, function, or site), horizon in months, period steps (monthly for a 12 month plan, quarterly beyond that), role families with levels and locations, and who owns each input. CIPD guidance is that plans should reflect strategy, use internal and external information rather than history alone, and stay robust for short term operations while flexing across scenarios. Record scope and the decision the plan feeds (budget round, board approval, recruiting capacity) at the top of the plan.

1. Build the demand table by role. Use the methods in references/models.md and the tool for the arithmetic. Driver or ratio method when workload data exists, growth and productivity when a volume forecast exists, trend only for stable work, structured judgement for new work, and a working back from cost check against the funded budget. Every productivity gain needs a named cause (a tool, a process change, automation of a named task). Demand is by role, level, location, and critical skill, per period. Never present one total alone.

bash
   python3 scripts/workforce.py demand --driver-volume 12000 --units-per-fte 300
   python3 scripts/workforce.py demand --current-fte 20 --growth-rate 0.25 --productivity-gain 0.10
   

1. Build the supply table with a stock and flow model, per role. Start from current headcount, subtract exits from the attrition rate, subtract retirements as their own count, subtract transfers and promotions out, add transfers and promotions in. Keep voluntary exits, involuntary exits, and retirements as separate lines, following the separations split the US Bureau of Labor Statistics uses in JOLTS. The attrition rate excludes retirements or the model double counts them. Add a short external supply note per critical role: pool depth, competing employers, pipeline sources. Use scripts/workforce.py supply for a period by period view of one role.

1. Run the gap analysis with the bundled tool on a CSV shaped like references/example-roles.csv (columns: role, current, demand, attrition_rate, retirements, transfers_in, transfers_out, time_to_fill_days, ramp_months, fully_loaded_cost).

bash
   python3 scripts/workforce.py plan --input references/example-roles.csv --horizon-months 12 --scenario base
   

Read the gap four ways: quantity (heads short or surplus), skill (named skills short inside a role whose count looks fine), timing (supply arriving after the demand date), and cost (demand staffing at fully loaded cost against the funded budget). The tool exits with code 1 when any role is short, so a plan with open gaps cannot pass as clean. The full worked example, with every number reproduced from the tool, is in references/worked-plan.md: 121 current staff, demand 141, supply before hiring 98.9, and 44 hires needed, split between replacement and growth.

1. Choose a response per gap before counting hires as the answer. Options, drawn from CIPD and SHRM practice: build (train, reskill, promote), buy (external hire), borrow (contract, agency, partner capacity for a fixed scope), redeploy (move people from surplus to shortage with retraining time counted), redesign (change the work, the team shape, or automate a named task so demand itself falls), and retain (fix the cause of voluntary exits when replacement hiring is the larger cost). For a surplus: redeploy first, then reskill, then let natural attrition work, then reduce contingent capacity, and treat exits as a last resort that needs its own legal and human review. Record the chosen response, owner, and date per gap. Hiring is the default only after the other options have a written reason against them.

1. Sequence the hiring plan by start date, not by gap size. For each role the tool computes start recruiting by month from your own time to fill plus ramp time: a role with a long fill and ramp starts early even when its gap is small. Check the sequence against recruiter capacity, interview capacity, and onboarding capacity per month, and flag any month the plan exceeds them. State the assumed hires per month out loud in the plan.

1. Run at least three scenarios on the same table structure: base (the funded forecast), growth (higher volume), and squeeze (lower volume or a cut budget, often with higher attrition). Change assumptions only, using the tool multipliers, and record per scenario the assumption values, hires and cost totals, roles flagged short, and the trigger that releases or pauses hiring (a signed contract, a volume threshold, a date).

bash
   python3 scripts/workforce.py plan --input references/example-roles.csv --scenario growth --demand-multiplier 1.15 --attrition-multiplier 1.25
   

Roles short in every scenario get started now. Roles short in one scenario stay trigger based. That split is the main decision a scenario run should produce.

1. Close the loop on a cadence. Refresh the plan quarterly for a 12 month horizon, sooner when actual demand, attrition, or time to fill moves outside the assumed range. At each refresh, compare last period forecast against actuals per role (supply, exits, hires landed, time to fill), name the largest misses and their causes, and update the rates from evidence. A plan that is never scored against actuals gets more confident and less accurate at the same time.

Output Contract

Deliver a workforce plan containing, at minimum:

• Scope and assumptions header: planning unit, horizon, period steps, decision the plan feeds, data sources and the date each was pulled, and every rate with its source period and population.
• The demand table by role, level, and location, with the method used per role and the driver or growth and productivity inputs behind each figure.
• The supply table by role: current headcount, exits, retirements, transfers out and in as separate lines, and supply before hiring.
• The gap table: gap in heads and as a share of demand, hires needed split into replacement and growth, surplus where it exists, skill gaps inside roles, and demand cost against the funded budget.
• A gap action list: chosen response per gap (build, buy, borrow, redeploy, redesign, retain, or a surplus action), owner, and date.
• The sequenced hiring plan: hires per role per period, start recruiting by month per role, and any month that exceeds recruiting or onboarding capacity, flagged.
• The scenario comparison: base, growth, and squeeze with assumption values, hires and cost totals, roles short in all scenarios, and the trigger attached to each contingent hire.
• Forecast accuracy from the last cycle, where a last cycle exists: forecast against actual per role, the largest misses, and what rate or assumption changed as a result.

Operating Rules

• Plan in roles and flows, never in totals alone. A total can balance while the one role the business depends on is short, and aggregate attrition hides the role losing people at twice the company rate.
• Keep exit lines separate and never double count retirements. Voluntary exits, involuntary exits, and retirements have different causes and different fixes. If a source rate bundles them, unbundle it or zero the separate count.
• No invented benchmarks. Time to fill, attrition, ramp, and cost figures come from the organisation's own records or a named source the reader can inspect. Thresholds inside the tool, such as the 20 percent large gap flag, are planning heuristics, not published standards, and the plan must say so if it relies on them.
• Use workforce data in aggregate and for planning only. Forecast flows for groups, never score individual people for likely exit using personal characteristics, and keep protected characteristics out of supply and attrition modelling. Surplus and exit decisions about real people need human review and local legal advice, not a model output.
• Treat internal moves as two sided. A promotion in is supply for one role and a loss for another. A plan that counts the gain and skips the loss overstates supply.
• State what would change the plan. Every contingent hire, freeze, or redeployment carries its trigger and the date the trigger is checked. A plan with no triggers forces a full rebuild at the first surprise.
• Handle the underlying files as confidential HR material. Headcount, cost, and exit data by role can identify small teams and individuals. Share on a need to know basis and keep named personal notes out of the planning tables.