2025-06-10

OpenAPI diffs as stand-up theater

By Lan Pham

Wide monitor showing schema diff

REST Contract Design Studio graduates keep sending us stand-up recordings—audio optional—where diffs are read aloud like poetry. It sounds odd until you hear ambiguous verbs caught in real time.

The first paragraph explains the ritual: author reads additions, reviewer reads removals, neutral facilitator marks questions. Rotating roles prevents hero worship.

Paragraph two covers tooling agnosticism. Spectral rules matter, but human tone catches confusing examples. We show a before/after example block where only comments changed yet consumer confusion dropped.

The third paragraph acknowledges fatigue. Meetings longer than eighteen minutes revert to async diffs. Structure beats marathon politeness.

We close with a reminder that syllabus weeks include peer swaps, not only mentor eyes. Peer review is professional growth, not a downgrade.