capacity-planner

# Capacity Planner

Turns headcount into hours you can actually commit. Most capacity plans fail the
same way: they count people instead of delivered hours, ignore ramp, and size
supply to fit the roadmap rather than the other way round. This skill computes
effective capacity independently, matches it against risk-adjusted demand, and
publishes the cut line.

## When to use this skill

- **Quarterly planning** — deciding what the team can commit to for the next 90 days
- **Testing a roadmap** — a stakeholder has a list and wants to know if it fits
- **Building a hiring ask** — quantifying a structural gap in hours and dollars
- **Hire vs contract vs defer** — choosing how to close a capacity shortfall
- **Mid-quarter replan** — the burn rate diverged and commitments need renegotiating
- **Onboarding impact** — modelling what three new hires actually deliver this quarter

## Inputs the skill expects

- Team roster: name, discipline, seniority, FTE, tenure in months
- Known absence: booked PTO days, on-call rotation weeks per person
- Overhead estimates: meeting load and non-delivery overhead as a percentage
- Working days and hours per day for the period
- Candidate commitments with discipline, hour estimate, confidence band, and priority
- For scenario work: demand curve per quarter, salary/contractor rates, start dates

## Clarify First

Before generating, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Is this a supply question or a demand question?** — sizing a hiring ask and testing a roadmap use different scripts and produce different artifacts
- [ ] **Who counts as delivery capacity?** — including managers, tech leads, or unfilled reqs at full FTE changes the answer by 10-40%
- [ ] **Are the estimates already risk-adjusted?** — applying the confidence inflation twice overstates demand by 40%+; applying it zero times understates it by the same
- [ ] **Is the buffer set from history or from intent?** — the unplanned-work reserve is the single largest lever on the cut line

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Workflows

### Workflow 1 — Model effective capacity

Establishes what the team can actually deliver, computed before anyone looks at
the roadmap. Run this first, always.

1. Build the roster: one entry per person, with real FTE and tenure in months. Use a negative `tenure_months` for someone who has not started yet.
2. Pull **booked** PTO, not average PTO. Q3 and Q4 are not average quarters.
3. Set `meeting_load_pct` from a calendar audit, not from memory — the gap is usually 5-10 points.
4. Run the model and check the effective-hours ratio against the sanity band in `references/capacity-benchmarks.md`: below 45% is structurally broken, above 80% is fiction.
5. Record the per-discipline effective hours — these are the inputs to Workflow 2.

```bash
python3 business-operations/capacity-planner/scripts/capacity_model.py \
  --input business-operations/capacity-planner/assets/sample_team.json \
  --format text
```

### Workflow 2 — Find the cut line

Matches risk-adjusted demand against capacity in priority order and reports what
does not fit.

1. List every candidate commitment with discipline, raw estimate, confidence band, and priority. Mark anything already promised externally with `"committed": true`.
2. Set the buffer from the trailing three quarters of actual unplanned hours. Default 20%; use 30% if the team owns customer-facing incidents.
3. Run the gap analysis and read the cut line, not the totals.
4. Escalate any `committed: true` item above the cut line **this week** — a promise you already know you will miss is a conversation, not a risk.
5. Publish the below-the-line list alongside the plan. That list is the deliverable.

```bash
python3 business-operations/capacity-planner/scripts/commitment_gap.py \
  --input business-operations/capacity-planner/assets/sample_commitments.json \
  --buffer-pct 20 --format text
```

### Workflow 3 — Compare hire, contract, and defer

Applies only to work below the cut line. Never use scenario analysis to justify
a plan that does not fit.

1. Build the demand curve per quarter for the horizon — at least four quarters, eight if the gap looks structural.
2. Define one scenario per realistic option, including a defer scenario as the zero-cost baseline.
3. Run the comparison and read four axes, not just cost: time to relief, cost per delivered hour, reversibility, and knowledge retention.
4. Sense-check the winner against the decision rule in `references/planning-methods.md`. A four-quarter horizon is systematically biased toward contracting because the hire/contract crossover falls at month 9-14.
5. Write the recommendation with its lead time attached. "Hire two engineers" relieves the quarter after next, not this one.

```bash
python3 business-operations/capacity-planner/scripts/scenario_compare.py \
  --input business-operations/capacity-planner/assets/sample_scenarios.json \
  --format json
```

## Decision frameworks

### Gross-to-effective conversion [PROVEN]

Planning figures for one fully-ramped IC over a 63-day quarter:

| Layer | Hours | Running total |
|-------|-------|---------------|
| Gross (63 d x 8 h) | 504 | 504 |
| Booked PTO (5 days) | -40 | 464 |
| On-call (2 weeks @ 40% loss) | -32 | 432 |
| Meetings + overhead (20%) | -86 | 346 |
| Unplanned-work buffer (20%) | -69 | **277 committable** |

**Use 270-300 committable hours per fully-ramped IC per quarter.** A tech lead
delivers 120-160; an engineering manager delivers 0. A mid-level hire starting on
day one of the quarter delivers 90-110.

### Which lever closes the gap

| Gap size | Persists beyond 4 quarters? | Lever | Time to relief |
|----------|----------------------------|-------|----------------|
| Any | — | **Cut scope** [PROVEN] | Immediate |
| Under 10% | No | **Reduce overhead** [PROVEN] | 2-4 weeks |
| 10-3