# Health Engine & Demo Data — Final Report

Date: 2026-06-05  
Status: **Complete — ready for enterprise demo**

---

## Executive summary

The health engine no longer assigns misleading scores to empty projects. Notifications fire only when evidence-backed health degradation occurs. Enterprise demo data populates all major agile dashboards with realistic, divergent project scenarios.

---

## Bugs fixed

| Bug | Root cause | Fix |
|-----|------------|-----|
| New project shows score **74** / Needs Attention | Old model averaged components; `completion=0` → 74 | `initializing` state with `score: null` |
| False **Project Health At Risk** on create | Health snapshot + event on first calculate | Skip snapshot/event when `initializing` |
| Sprint alerts used wrong notification type | Monitor mapped to `PROJECT_HEALTH_CRITICAL` | Corrected to `SPRINT_HEALTH_*` types |
| Broken email placeholders | Missing variables in `data` payload | Pass all template variables; validate in `render()` |
| Milestone emails missing names | Monitor sent only `project_id` | Added `milestone_name`, `project_name` |

---

## Notifications fixed

- `NotifyOnHealthUpdated` — `shouldAlert()` gate, skips initializing  
- `AgileNotificationMonitorService` — template data completeness, correct sprint types  
- `NotificationTemplate::render()` — automated placeholder validation + exception

---

## Templates fixed

- Project health: `project_name`, `health_score` always passed when required  
- Sprint health: `sprint_name` passed  
- Milestones: `milestone_name` passed  
- Automated test prevents regression

---

## Demo data created

**Seeder:** `database/seeders/EnterpriseAgileDemoSeeder.php`  
**Wired in:** `DatabaseSeeder` (runs after `NotificationTemplateSeeder`)

### Projects (6 scenarios)

| Project | Target scenario | Verified score | Level |
|---------|-----------------|----------------|-------|
| MV Community App | Healthy | 85 | healthy |
| Owner Portal | Needs Attention | 74 | attention |
| Sales CRM | Healthy | 87 | healthy |
| Benefits Platform | At Risk | 39 | critical |
| Contractor Management | Delayed | 65 | attention (+ overdue) |
| Legacy HR Portal | Completed | 96 | healthy |

### Volume (verified on seed run)

| Entity | Count |
|--------|-------|
| Work items | 121+ |
| Completed items | 92 |
| Active/open items | 31 |
| Risks | 14 (4 critical) |
| Dependencies | 20 |
| Milestones | 9 |
| Sprints | 11 |
| Epics | 18 (3 per project) |
| Departments | 4 (INFRA, HR, PROD, DIGI) |
| Team members | 8+ |

---

## Screens / dashboards impacted

| Screen | Before | After |
|--------|--------|-------|
| Projects list | Empty or single test project | 6 enterprise projects with health badges |
| Portfolio dashboard | Empty health chart | Healthy / attention / critical distribution |
| Executive dashboard | Initializing conflated with at-risk | Clear message or real score + factors |
| Sprint analytics | No velocity history | Multi-sprint velocity per project |
| Risk matrix | Empty | 14 risks across portfolio |
| Gantt / forecast | No bars | Scheduled work + overdue/delayed projects |
| Capacity planning | No assignments | Team assignments with overload scenarios |

---

## Before vs after — new project

| | Before | After |
|---|--------|-------|
| Health score | 74 | `—` (null) |
| Health level | `attention` | `initializing` |
| Alert on create | Often yes | **No** |
| User message | None | "Start planning work to generate project health metrics." |

---

## Frontend updates

- `ProjectHealthLevel` includes `initializing`  
- `formatHealthLevel()`, null-safe score display (`—`)  
- Portfolio buckets exclude initializing from risk counts  
- Executive page shows initializing message

---

## Tests added

- `tests/Feature/Projects/ProjectHealthServiceTest.php`  
- `tests/Feature/Notifications/NotificationTemplateRenderTest.php`

---

## Documentation delivered

1. `docs/HEALTH_ENGINE_AUDIT.md`  
2. `docs/HEALTH_ENGINE_HARDCODED_VALUES.md`  
3. `docs/HEALTH_SCORING_MODEL.md`  
4. `docs/NOTIFICATION_AUDIT.md`  
5. `docs/TEMPLATE_VARIABLE_AUDIT.md`  
6. `docs/HEALTH_ENGINE_AND_DEMO_DATA_REPORT.md` (this file)

---

## Final recommendations

1. **Run full seed** on demo environments: `php artisan migrate:fresh --seed`  
2. **Handle `initializing`** in any new health UI components  
3. **Add `DEPENDENCY_BLOCKED` notification type** if real-time blocker alerts are required (currently surfaced via health factors only)  
4. **Update sprint lifecycle tests** — 3 pre-existing failures from `SprintStatus` enum migration (`CLOSED` → `COMPLETED`); unrelated to health fixes  
5. **Re-seed** if partial demo detected: delete projects named "MV Community App" etc. and re-run `EnterpriseAgileDemoSeeder`

---

## Success criteria — met

- [x] New project does not become "At Risk" without evidence  
- [x] No false health alerts on create/update/sprint create  
- [x] No hardcoded score 74  
- [x] Email templates render variables correctly (validated)  
- [x] Dashboards show realistic enterprise data after seed