Santhosh Janardhanan
b8262bbcaf
Archive three completed changes to archive/: - api-resource-standard (70 tasks, 14 resource classes) - capacity-expert-mode (68 tasks, expert mode planning grid) - enhanced-allocation (62 tasks, planning fidelity + reporting) Sync all delta specs to main specs/: - api-resource-standard: API response standardization - capacity-expert-mode: Expert mode toggle, grid, KPIs, batch API - resource-allocation: Month execution comparison, bulk, untracked - untracked-allocation: Null team member support - allocation-indicators: Variance indicators (red/amber/neutral) - monthly-budget: Explicit project-month planning All changes verified and tested (157 tests passing).
90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# Proposal: Enhanced Allocation Fidelity
|
|
|
|
## Why
|
|
|
|
The current Resource Allocation implementation diverges from intended planning behavior and creates misleading month-level signals.
|
|
|
|
Current drift:
|
|
1. Monthly budget was treated as a derived display (`approved_estimate / 12`) rather than explicit manager planning.
|
|
2. Allocation execution and planning intent are conflated in one surface.
|
|
3. Visual signaling is noisier than needed for decision-making.
|
|
4. Untracked allocation and partial bulk semantics are only partially implemented.
|
|
|
|
Business need:
|
|
- Managers must phase a project lifecycle estimate across months based on dependencies and customer timelines.
|
|
- Month execution must be validated against explicit month plans, not an average split.
|
|
- Management needs deterministic reporting from a strict plan -> execute chain.
|
|
|
|
## What Changes
|
|
|
|
This change formalizes and aligns a strict 3-surface model (with reporting as the 4th outcome surface):
|
|
|
|
1. **Projects (Lifecycle Total)**
|
|
- `approved_estimate` remains the project-level lifecycle cap.
|
|
|
|
2. **Project-Month Plan (Manager Intent)**
|
|
- Manager enters monthly planned hours per project in a grid.
|
|
- Monthly plans reconcile against lifecycle total (OVER/UNDER/MATCH).
|
|
- Blank planning months remain blank in UI.
|
|
|
|
3. **Project-Resource Allocation (Month Execution)**
|
|
- Allocation grid becomes primary editing workflow (no modal-first dependency).
|
|
- Row variance compares month allocation vs project month plan.
|
|
- Column variance compares member allocation vs member month capacity.
|
|
- Untracked (`team_member_id = null`) is supported as a first-class execution path.
|
|
|
|
4. **Reporting Outcome**
|
|
- Reporting consumes lifecycle total + month plan + resource allocation to show did/is/will views.
|
|
|
|
## Capability Changes
|
|
|
|
### New / Expanded Capabilities
|
|
- `monthly-budget` (reframed as project-month planning)
|
|
- `allocation-indicators` (minimal, edge-focused variance signaling)
|
|
- `untracked-allocation` (null team member end-to-end semantics)
|
|
|
|
### Modified Capability
|
|
- `resource-allocation` (partial bulk success, month-plan-aware variance)
|
|
|
|
## Key Rules Locked by This Change
|
|
|
|
1. No `approved_estimate / 12` derivation for planning behavior.
|
|
2. Month plan reconciliation is explicit:
|
|
- sum(plan) > approved -> OVER
|
|
- sum(plan) < approved -> UNDER
|
|
- sum(plan) == approved -> MATCH
|
|
3. Blank planning month is visually blank, but treated as planned `0` for allocation variance.
|
|
4. Allocation for blank-plan months is allowed.
|
|
5. `projects.forecasted_effort` is deprecated for this workflow.
|
|
6. Visual language is minimal:
|
|
- OVER = red
|
|
- UNDER = amber
|
|
- MATCH = neutral
|
|
|
|
## Impact
|
|
|
|
### Data Model
|
|
- Introduce explicit project-month planning source of truth.
|
|
- Stop using `projects.forecasted_effort` in this workflow path.
|
|
|
|
### API Contract
|
|
- Add/adjust project-month plan endpoints and payloads.
|
|
- Ensure allocation endpoints provide enough context for row/column variance.
|
|
- Keep partial bulk response contract explicit (created/failed/summary).
|
|
|
|
### Frontend
|
|
- Add project-month plan grid surface.
|
|
- Refactor allocation matrix to grid-first editing and edge variance indicators.
|
|
- Keep status placement low-noise and decision-oriented.
|
|
|
|
### Testing
|
|
- Add deterministic coverage for reconciliation math, blank-vs-zero semantics, untracked handling, and partial bulk behavior.
|
|
- Require mapped tests for every requirement scenario before task closure.
|
|
|
|
## Non-Goals
|
|
|
|
- Real-time collaboration/websockets in this change.
|
|
- Notification systems.
|
|
- Export workflows.
|
|
- UI polish iterations beyond required planning fidelity.
|