# Engineering Demo Video Lessons Learned

## Scope

This postmortem comes from producing a real 3-5 minute FNTK cross-agent demo using GitHub Copilot CLI, Codex CLI, Claude Code CLI, and Microsoft Fabric Notebook UX.

## What worked

- A short opening slide established the scenario and installation commands.
- Real CLI footage was more credible than transcript replay or simulated slides.
- Separate raw clips made it possible to replace one agent segment without re-recording everything.
- Fixed-rate Microsoft TTS kept speech speed consistent.
- Explicit corner labels made agent transitions understandable.
- Showing the final Fabric Notebook proved that CLI actions persisted in the product.
- FFmpeg contact sheets made full-timeline review fast.

## What failed and why

### Automated OBS recording under RDP

**Symptom:** long black sections, incorrect monitor selection, or unstable capture after display changes.

**Cause:** RDP, monitor topology, and OBS capture-method behavior changed independently.

**Lesson:** run a 10-second preflight after every monitor/RDP change. If reliability is uncertain, switch to manual per-segment recording early.

### Fit-to-screen made CLI text too small

**Symptom:** 1920x1080 output existed, but terminal text was not readable.

**Cause:** a high-resolution desktop was scaled into a 1080p OBS canvas.

**Lesson:** increase terminal font size and window zoom before capture. Post-production sharpening cannot restore missing pixels.

### Crop and aspect-ratio errors

**Symptom:** CLI edges were missing, the screen did not fill the frame, or the image looked vertically stretched.

**Cause:** crop coordinates were chosen without inspecting the active canvas; wide content was forced to 1920x1080.

**Lesson:** inspect source frames first. Crop only inactive canvas, then use proportional scale and pad.

### Story-state leakage

**Symptom:** the baseline Fabric UX showed content added later by Claude Code CLI.

**Cause:** a convenient final-state clip was reused in an earlier section.

**Lesson:** track an explicit state contract for every segment. Source convenience never overrides timeline truth.

### False agent/action claims

**Symptom:** narration said the workflow switched back to GitHub Copilot CLI even though the remaining footage was Claude Code CLI.

**Cause:** narration and labels followed an outdated storyboard after the edit changed.

**Lesson:** regenerate labels, captions, and narration from the final visual timeline. The visible action is the source of truth.

### Page-open loops

**Symptom:** Fabric UX appeared to open, then opened again a few seconds later.

**Cause:** an opening clip was followed by another copy of the same source range.

**Lesson:** play one opening sequence, then hold the stable final frame.

### Long silence and static footage

**Symptom:** fixed-rate narration was correct but left 7-16 second silent spans; Claude footage froze for too long.

**Cause:** short narration sentences were placed at coarse section boundaries, and footage was frozen to fill the remaining duration.

**Lesson:** keep voice rate constant, but rewrite useful narration to cover visible actions. Prefer continuous source playback at moderate speed over long freezes.

## Review metrics

| Metric | Initial revision | Smooth revision |
|---|---:|---:|
| Longest detected narration gap | 16.3 s | about 6.5 s |
| Delivery resolution | 1920x1080 | 1920x1080 |
| Frame rate | 30 FPS | 30 FPS |
| Black segments | 0 | 0 |
| Narration speed manipulation | None | None |
| Final hold after narration | Immediate cut | about 3 s |

## High-value review order

1. Watch agent/UX transitions at normal speed.
2. Inspect five-second contact sheets for repetition and stale state.
3. Inspect one second before/at/after each chapter boundary.
4. Run black and silence detection.
5. Verify labels and narration against the visible CLI.
6. Confirm the final page stays stable after it opens.
7. Generate and record the checksum only after all edits are complete.