Decision: conflict UX on revision mismatch #3

New issue

Closed

opened 2026-07-23 14:46:22 +02:00 by cloudbot · 1 comment

cloudbot commented

2026-07-23 14:46:22 +02:00

Collaborator

Decision #3 — how should the app behave when the target note's Outline revision changed since our last write (someone else edited the same note)?

The sync model is create-once, then replace: every subsequent debounce tick and the final Publish re-check the document's revision before reconstructing this entry's block. If the revision moved, we must not silently overwrite.

The two candidate behaviours

Hard-block Publish — refuse to write, tell the user to resolve it in Outline first. Safe but a dead end inside the app.
Offer a choice (prototype's approach) — an inline banner in the entry card (warn/bg), "⚠ Someone else edited this note too", with three pill actions:
- Keep mine (filled orange) — our version wins,
- Keep theirs (outline) — discard our block, take the current note,
- Merge in Outline (text) — open the note to reconcile manually.

The committed prototype (design/Family App.dc.html) and the design-system skill both implement the second option and mark it the resolved answer.

What to decide

Confirm the Keep mine / Keep theirs / Merge in Outline banner (vs a hard block) so the sync engine and Stream UI can build to it.

Blocks: the sync engine conflict path and the Stream entry-card conflict state.

Recommendation: adopt the three-action banner as the prototype already specifies — it keeps resolution in-app and never silently loses either side's edits. Hard-blocking is strictly worse UX for a family app where the "conflict" is usually just two phones touching the same note.

Source: Solution Design — Family App v1 §7 (doc vpBNbG4TsV), decision §13 #3; prototype design/Family App.dc.html; skills/design-system/SKILL.md (Interaction patterns → Conflict resolution).

**Decision #3 — how should the app behave when the target note's Outline revision changed since our last write (someone else edited the same note)?** The sync model is create-once, then replace: every subsequent debounce tick and the final Publish re-check the document's `revision` before reconstructing this entry's block. If the revision moved, we must not silently overwrite. ### The two candidate behaviours - **Hard-block Publish** — refuse to write, tell the user to resolve it in Outline first. Safe but a dead end inside the app. - **Offer a choice** (prototype's approach) — an inline banner in the entry card (`warn/bg`), **"⚠ Someone else edited this note too"**, with three pill actions: - **Keep mine** (filled orange) — our version wins, - **Keep theirs** (outline) — discard our block, take the current note, - **Merge in Outline** (text) — open the note to reconcile manually. The committed prototype (`design/Family App.dc.html`) and the design-system skill both implement the second option and mark it the resolved answer. ### What to decide Confirm the **Keep mine / Keep theirs / Merge in Outline** banner (vs a hard block) so the sync engine and Stream UI can build to it. **Blocks:** the sync engine conflict path and the Stream entry-card conflict state. **Recommendation:** adopt the three-action banner as the prototype already specifies — it keeps resolution in-app and never silently loses either side's edits. Hard-blocking is strictly worse UX for a family app where the "conflict" is usually just two phones touching the same note. **Source:** Solution Design — Family App v1 §7 ([doc vpBNbG4TsV](https://outline.marquezkeenan.family/doc/solution-design-family-app-v1-vpBNbG4TsV)), decision §13 #3; prototype `design/Family App.dc.html`; `skills/design-system/SKILL.md` (Interaction patterns → Conflict resolution).

cloudbot added this to the M0 · Open Questions & Decisions milestone

2026-07-23 14:46:22 +02:00

cloudbot added the

spike

label

2026-07-23 14:46:22 +02:00

cloudbot added a new dependency

2026-07-23 14:46:50 +02:00

#41 Stream: inline conflict resolution UI