Envelope Tools

All envelope tools require Manager or Owner role unless noted. See Envelopes for conceptual background.

---

allocate_hours

Create a per-person hour envelope on a project.

Writes to: 07. Budgets

Parameters:

Param	Required	Description
requesting_user_slack_id	✅
project_name	✅
user_name or user_slack_id	✅	Person receiving the envelope
allocated_hours	✅	Hours for this envelope
task_id or task_name		Optional work-category tag

Returns: envelope id (use for updates/cancellations), and overbooked: true if the person is over capacity.

If overbooked: true is returned, always surface the warning: "⚠️ [Name] is overbooked by Xh."

---

update_allocation

Change the hours or task on an existing envelope.

Updates: 07. Budgets col D (hours), col I (task)

Parameters:

Param	Required	Description
requesting_user_slack_id	✅
allocation_id	✅	The envelope's ID
new_allocated_hours		New hours value
new_task_id or new_task_name		New task category

To find the envelope ID, call get_allocations or get_person_allocation_summary first.

Restrictions: Cannot target a Retainer or Agile parent project — envelopes must reference the active period or sprint child. The error message names the active period to guide the user.

Audit: The audit message shows exactly what changed (e.g. "40h → 50h" or "task: Design → Development").

---

cancel_allocation

Mark an envelope as cancelled. The record is kept for audit purposes.

Updates: 07. Budgets col F (status → "cancelled")

Parameters: requesting_user_slack_id, allocation_id

---

get_allocations

List envelopes with optional filters.

Reads from: 07. Budgets, 03. Users, 02. Projects

Parameters:

Param	Description
requesting_user_slack_id
user_id	Filter by person
project_id	Filter by project
status	"active" (default) or "cancelled"

---

get_my_allocations

The requesting user's active envelopes.

Parameters: requesting_user_slack_id

---

get_my_assignments

"What should I work on?" — returns active envelopes for the requesting user with remaining hours.

This is the primary tool for Users to understand their current workload. It shows:

• Projects they're allocated to
• Hours allocated vs. hours logged
• Hours remaining in each envelope

Parameters: requesting_user_slack_id

Any active user. Assignment = having an active envelope. Anyone can log time to any project regardless of assignment — envelopes are a planning tool, not a gate.

---

get_project_assignments

Who is allocated to a project. Manager/Owner.

Reads from: 07. Budgets, 03. Users

Returns: user_id, user_name, allocated_hours, hours_logged, hours_remaining, task_id (if tagged), status

Permission: Owners see all. Managers see only their assigned projects.

---

get_person_allocation_summary

All envelopes for one person across all their projects.

Reads from: 07. Budgets, 02. Projects

Parameters: requesting_user_slack_id, user_name

Returns per envelope: project_name, allocated_hours, hours_logged, hours_remaining, status, overdraw flag

---

get_project_allocation_summary

All envelopes for one project.

Reads from: 07. Budgets, 03. Users

Parameters: requesting_user_slack_id, project_name

---

get_team_availability

Remaining hours per person across all active envelopes.

Reads from: 07. Budgets, 01. Time Entries, 03. Users

Returns per person: available_hours, allocated_hours, remaining_hours, overbooked flag

Use this for a quick capacity snapshot before adding new work.

---

get_estimates_vs_actuals

Compare allocated hours (the plan) against logged hours (the actuals).

Reads from: 07. Budgets, 01. Time Entries

Parameters:

Param	Description
requesting_user_slack_id
week_start	"this week", "last week", or YYYY-MM-DD
user_name	Optional — filter to one person
project_name	Optional — filter to one project

Returns: per person/project: allocated_hours, actual_hours, delta

• delta > 0 = over plan (more hours worked than allocated)
• delta < 0 = under plan (fewer hours than allocated)

Surface meaningful divergences (delta ≥ ±20%) as insights. Never show estimates vs actuals for future weeks — redirect to get_allocations instead.

---

check_capacity

Can the team absorb new work? Takes discipline requirements and a timeline.

Parameters:

Param	Description
requesting_user_slack_id
discipline_requirements	Array of {discipline, hours_needed}
start_date	YYYY-MM-DD
end_date	YYYY-MM-DD

Returns per discipline:

• fte_sufficient: FTE has headroom — names and available hours
• fte_partial: FTE bench partially covers — gap amount
• contractor_required: No FTE capacity — hours of contractor coverage needed
• Contractor conflicts flagged if any contractors are double-booked

---

get_capacity_forecast

N-week rolling capacity outlook.

Parameters:

Param	Description
requesting_user_slack_id
weeks	Number of weeks to forecast (default 4, max 12)

Returns per week:

• week_start, utilisation_percent, unallocated_hours
• uncovered_projects: projects with no one allocated that week
• overbooked users: name + hours over

Interpretation:

• < 70% utilisation → plenty of headroom
• 70–90% → healthy

• 90% → nearly full, be careful

• uncovered_projects → flag immediately — no coverage that week