jacobh2/kvitt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UX: category suggestion rule and evidence from the Splitwise export; importer mapping gap

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jacob Hagstedt
2026-10-18 07:38:39 +02:00
parent 01b36e77b2
commit 4c1a4b5a9d
2 changed files with 120 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ux/proposed-decisions.md
+14 -7
View File
@@ -29,13 +29,20 @@ Every entry has: the owner's answer or the finding, the proposed decision text f
* **Decision (owner, 2026-10-18):** for a new expense, the editor selects a category from the description as the user types, while the user has not picked a category by hand in this editor session: (1) history match, (2) built-in keyword list, (3) the AC-8.6 default. The user can always change it. Editing an existing expense never changes its category automatically.
* **Why:** most expenses repeat the same shops; fewer taps in the ten-second flow (§13.1).
* **Spec changes (to be completed from `category-suggestion.md` when the analysis finishes):**
* AC-8.6: add the suggestion as the first source of the category default.
* New rule section (proposed §9.11 "Category suggestion"): normalisation, history match and tie-break, keyword matching, skipped archived/deleted categories, when the suggestion stops.
* New contract file: the keyword list (proposed path `contracts/category-keywords.csv`, columns `keyword,match,default_key,source`; draft in `docs/ux/category-keywords.csv`), versioned like other contract files.
* §14.2.4 contract change: `ExpenseRepository` gains `suspend fun suggestCategory(description: String): CategoryId?` (computed in `:data` from Room history and the keyword list, with a pure function in `:domain`); the editor calls it on description changes.
* §14.5: the pure function and its test vectors (Kotlin only, like analytics).
* **Evidence** (chronological replay of the household's 1 775 Splitwise expenses, aggregates only, `category-suggestion.md`): history step right 92.3 % of the time and used for 71.5 % of rows; keyword step 94.2 % on 7.8 %; overall 79.5 % correct versus 31.9 % for today's AC-8.6 default alone. At cold start (no history) keywords fire on 78 % of rows and are right 96 % of the time.
* **Spec changes:**
* AC-8.6: the category default becomes "the suggestion of §9.11, which falls back to the current rule".
* New §9.11 "Category suggestion": the text CS-1 to CS-7 of `category-suggestion.md`.
* New contract file `contracts/category-keywords.csv` (columns `keyword,match,default_key,source`; draft `docs/ux/category-keywords.csv`, 149 entries), listed in §14.8.
* §14.2.4: `ExpenseRepository` gains `suspend fun suggestCategory(accountId: AccountId?, description: String): CategoryId?` (computed in `:data` from Room and the keyword table; the editor calls it on description and account changes while the category was not picked by hand).
* §14.5: a pure Kotlin function `suggestCategory(description, history, keywords, activeCategories, fallback)` in `:domain` with test vectors (Kotlin only, like analytics).
* `strings.csv`: `expense_editor_category_suggested` "Vald utifrån beskrivningen" / "Chosen from the description".
* **Open points** (owner, low stakes; defaults in brackets): keep the five keywords that pick Övrigt, e.g. insurance words [keep]; "most recent" vs "most frequent" history match, the latter about one point better [most recent, as chosen].
## UX-7 §10.8 misses nine Swedish Splitwise category names
* **Finding** (from the export analysis): 21 rows use Swedish Splitwise category names that the §10.8 mapping table lacks: Utbildning (4), Tjänster (3), Livet - Övrigt (3), Kläder (3), Städning (2), Flyg (2), Spel (2), Verktyg - Övrigt (1), Cykel (1). They would import as `other` with a warning.
* **Proposed decision:** add them to the §10.8 table and `server/crates/kvitt-import/data/splitwise_categories.csv` by their English equivalents: Utbildning → other, Tjänster → home, Livet - Övrigt → other, Kläder → shopping, Städning → utilities, Flyg → travel, Spel → entertainment, Verktyg - Övrigt → utilities, Cykel → transport. (Needed by M9.)
## UX-4 S-1 asks for the display name
@@ -62,5 +69,5 @@ Every entry has: the owner's answer or the finding, the proposed decision text f
## Status
* U1: delivered (`d27f92e` rebased on `main`), direction picked.
* In progress: muted Kalas revision; keyword list and suggestion analysis from the Splitwise export.
* Done: muted Kalas revision (`directions/3-kalas/`, awaiting the owner's look); keyword list and suggestion analysis (`category-keywords.csv`, `category-suggestion.md`).
* Next: owner approves the muted palette → U2 `design-spec.md`, renamed `strings.csv`, per-screen PNGs, and the final values for UX-3 and UX-5.