From 942d7e88cc92dd74dce7cfccce4f879733bcf164 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 28 May 2026 08:23:29 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20refine=20porting=20rule=20=E2=80=94=20e?= =?UTF-8?q?xact=20on=20behavior+feel,=20idiomatic=20on=20implementation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operator guidance: parity is about the user experience (layout, copy, states, and especially responsiveness — caching exists to make the UI feel instant), not literal transliteration of Flutter's Dart. Replicate the behavior faithfully but reach it with the best well-supported native mechanism (Room+Flow, Compose, WorkManager, Media3) rather than copying drift watch() / Riverpod invalidate. A more native approach that improves the UX is preferred — recorded as an intentional divergence in the parity map. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ea92487b..892e0558 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,10 +13,17 @@ exists in Flutter: opened the Flutter file in this session, you have not earned the right to write the Android version. -2. **Replicate it exactly.** Match the behavior, the layout structure, the - section order, the empty/loading/error states, the copy strings, the data - sources, and the edge cases. Same number of rows, same fields per row, same - tap targets. +2. **Replicate the user-visible behavior exactly; implement it idiomatically.** + Match what the user sees and feels: layout structure, section order, empty/ + loading/error states, copy strings, edge cases, and — critically — the + **responsiveness** (the app caches to make the UI feel instant; preserve + that). But you do NOT have to copy Flutter's *implementation*. Flutter uses + drift `watch()` + Riverpod `invalidate`; the well-supported Android idioms + are Room + Flow, Compose state, WorkManager, Media3. **Prefer the native + mechanism that delivers the same or better UX** over a literal transliteration + of the Dart. Exact on behavior + feel; idiomatic on structure. If a more + native approach genuinely improves the experience, do that (and note it in + the parity map as an intentional, better-supported divergence). 3. **Never silently substitute a different design.** If the faithful port seems hard, blocked, or impossible, STOP and verify by reading more of the Flutter