# Hotreload Sentinel

> AI-assisted .NET MAUI Hot Reload diagnostics. Monitors hot reload sessions, validates environment setup, tracks per-change developer confirmations, and generates bug reports. Use when hot reload isn't working, UI doesn't update after code changes, or for monitoring hot reload sessions in real-time.

- Skill: `davidortinau/hotreload-sentinel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davidortinau/hotreload-sentinel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidortinau/hotreload-sentinel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: davidortinau (https://skillmd.com/u/davidortinau)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidortinau/hotreload-sentinel

---


# Hot Reload Sentinel — Copilot Skill

## Project Setup Workflow (when asked to "set up monitoring")

When a developer asks to set up a project for hot reload monitoring, do this before monitoring:

1. Find the MAUI project (`.csproj`) and `MauiProgram.cs` in the target project.
2. Check whether `HotReloadSentinel.Diagnostics` package is already referenced.
3. Check whether `MauiProgram.cs` already contains `builder.UseHotReloadDiagnostics();`.
4. Only if missing, apply setup:
   - Run `dotnet add package HotReloadSentinel.Diagnostics` in the project directory.
   - Update `MauiProgram.cs`:
     - Add `using HotReloadSentinel.Diagnostics;` inside `#if DEBUG` blocks
     - Add `builder.UseHotReloadDiagnostics();` inside `#if DEBUG` after builder creation
5. Re-check and report exactly what was changed.

Do not assume VS Code; this setup applies to both VS Code and Visual Studio projects.

## Monitoring Workflow

When a developer asks to "watch hot reload", "monitor hot reload", or any hot-reload related task:

### Step 1: Prerequisites Check (ALWAYS do this first)

1. Call `hr_diagnose` to validate the environment
2. Review results for any `fail` or `warn` status checks
3. If prerequisites are unmet, report them clearly to the developer:
   - Missing ENC log directory → explain it must be set before launching the IDE
   - Missing BOM on .cs files → offer to auto-fix with `hr_diagnose --fix`
   - Missing MetadataUpdateHandler → offer to scaffold one for their framework
   - VS Code settings not configured (when VS Code is in use) → offer to auto-fix
4. Ask the developer if they'd like you to fix any auto-fixable issues before proceeding
5. If critical prerequisites are unmet (no ENC log dir, no Session.log), stop and explain — watching without these will produce no useful data

### Step 2: Start Monitoring

1. Call `hr_watch_start` to start the background watcher
2. Call `hr_status` to confirm watcher is alive and check heartbeat connectivity
3. If heartbeat is not detected, warn the developer that app-side diagnostics (HotReloadSentinel.Diagnostics NuGet) may not be installed

### Step 3: Follow and Confirm

1. Call `hr_watch_follow` (with seconds=60) to stream events
2. When output contains `follow_pending_confirmation=true`:
   - Call `hr_pending_atoms` to get the change atoms
   - For each atom, use `ask_user` to confirm with the developer individually
   - Record all answers with `hr_record_verdict`
3. Repeat `hr_watch_follow` to catch more events — do NOT wait for the developer to prompt you
4. When done, call `hr_watch_stop`
5. If failures were recorded, offer to call `hr_draft_issue` to generate a bug report

## Environment Setup Requirements

### CRITICAL: ENC Log Directory
```bash
# Must be set BEFORE launching your IDE (VS Code or Visual Studio)
export Microsoft_CodeAnalysis_EditAndContinue_LogDir=/tmp/HotReloadLog  # macOS/Linux
```
```powershell
# Windows (persistent; restart terminal after running)
setx Microsoft_CodeAnalysis_EditAndContinue_LogDir "%temp%\HotReloadLog"
```

### File Encoding
All `.cs` files MUST be UTF-8 with BOM. Files without BOM will silently fail hot reload.

### VS Code Settings (VS Code users only)
```json
{
  "csharp.experimental.debug.hotReload": true,
  "csharp.debug.hotReloadOnSave": true,
  "csharp.debug.hotReloadVerbosity": "detailed"
}
```

## MetadataUpdateHandler (Required for MauiReactor / C# Markup)

### MauiReactor
```csharp
[assembly: System.Reflection.Metadata.MetadataUpdateHandler(typeof(HotReloadService))]

internal static class HotReloadService
{
    public static void ClearCache(Type[]? updatedTypes) { }
    public static void UpdateApplication(Type[]? updatedTypes)
    {
        HotReloadTriggered?.Invoke();
    }
    public static event Action? HotReloadTriggered;
}
```
Base pages subscribe: `HotReloadService.HotReloadTriggered += () => Invalidate();`

### C# Markup (CommunityToolkit)
Implement `ICommunityToolkitHotReloadHandler` on pages.

### Standard XAML
Usually works without custom handler. If not, check linker settings.

## Diagnostic Reasoning

Use these rules when interpreting sentinel output:

| Scenario | Meaning | Action |
|---|---|---|
| ENC applied + heartbeat advanced + visual OK | Working correctly | Record as passed |
| ENC applied + heartbeat advanced + visual FAILED | UI framework rendering bug | File bug against MAUI/MauiReactor with diff + heartbeat proof |
| ENC applied + heartbeat NOT advanced | Delta didn't reach app or handler didn't fire | Check MetadataUpdateHandler registration |
| ENC applied + no heartbeat endpoint | Can't determine if app received delta | Recommend installing HotReloadSentinel.Diagnostics NuGet |
| ENC blocked | Compilation error | Show error message from Session.log |
| `not_applied` on active TFM | Stale build | Recommend rebuild |
| `not_applied_other_tfm` | Normal multi-TFM noise | Ignore |
| `ENC1008` | Rude edit | Restart debug session required |
| `connection_lost` | Debug session disconnected | Restart debug session |

## Common Failure Patterns

1. **"Nothing happens when I save"** → Check Debug config, F5 attached, file saved
2. **"Unsupported edit" / "Rude edit"** → Adding methods/fields/properties requires restart
3. **Changes apply but UI doesn't update** → Re-trigger code path, check MetadataUpdateHandler
4. **Shadow/style not rendering on specific controls** → Likely MAUI handler bug, file issue

## References

- [Diagnosing Hot Reload (MAUI Wiki)](https://github.com/dotnet/maui/wiki/Diagnosing-Hot-Reload)
- [Supported code changes (C#)](https://learn.microsoft.com/visualstudio/debugger/supported-code-changes-csharp)
- [XAML Hot Reload for .NET MAUI](https://learn.microsoft.com/dotnet/maui/xaml/hot-reload)