add-feature

name	add-feature
description	End-to-end workflow for adding a user-facing feature to SubKan — domain model, Room schema, repository, ViewModel, Compose screen, strings and tests, in the order that keeps the build green. Use when asked to add or extend a feature (a new field, a filter, notifications, export, a widget…), not for a one-line fix.

Adding a feature to SubKan

Work outward from the domain. Each step compiles on its own, so a mistake surfaces next to the code that caused it rather than 200 lines later.

1. Decide whether the schema changes

If the feature stores anything new, it does. Stop and run the room-migration skill first, then come back — retrofitting a migration after the UI is written means redoing the entity, the DAO and the tests.

If it stores nothing new (a filter, a sort, a display option), skip to step 3.

2. Domain model

Add or extend the type in core/model. Keep it Android-free: no Context, no @Composable, no androidx imports. Pure logic — totals, sorting, date buckets — goes here too, as top-level functions, because this is the layer that gets real unit tests.

Write those tests now, in app/src/test/java/com/subkan/core/model/. They run in about a second and they are the cheapest place to discover that the idea does not quite work. MonthlyTotalsTest shows the shape; subscription(...) in that file is the shared fixture builder.

./gradlew :app:testDebugUnitTest

Anything involving "today" takes a LocalDate parameter rather than calling LocalDate.now(). That is what AppClock is for, and it is why the countdown buckets are testable.

3. Data layer

• DAO — add queries to data/local/dao/. Return Flow for anything the UI observes. Use IS :param for nullable columns.
• Entity mapping — extend toDomain() / toEntity() in the same file as the entity.
• Repository — add the method to the interface in data/repository/ first, then implement it in the Offline* class. The interface is what the ViewModel sees; keep it in domain types.

If the change touches deletion, cascading, or card_id, add a case to PaymentCardDeletionTest. That file exists because the two card-delete semantics are the easiest thing in this app to break silently — read .claude/rules/room-data.md before changing either.

4. ViewModel

Extend HomeViewModel / CardsViewModel / SettingsViewModel, or add one under the relevant ui/ package.

• Expose one StateFlow<XxxUiState> built with combine(...).stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), initial).
• Put one-shot things — snackbars, undo offers — on the Channel-backed event flow, not in the state. State replays on rotation; a snackbar should not.
• Anything destructive returns enough to undo itself, the way DeletedCard does.
• Actions are plain functions returning Job via viewModelScope.launch { … }.

5. Strings, then UI

Add strings to res/values/strings.xml before writing the composable, so it is written against real resource ids. That file is Japanese and is the default locale — there is no values-ja/, and adding one would be a bug (see .claude/rules/resources.md).

Then the composable, under the matching ui/ package. Follow the existing screens: state in, callbacks out, MaterialTheme.colorScheme for every colour, stable keys on every list item.

Reuse components/SubscriptionRow, components/ServiceIcon, components/EmptyState rather than writing a new row — visual consistency across the list, the pager and the management screen is a feature.

A PostToolUse hook will reject a hard-coded Color(0xFF…) outside ui/theme/. That is working as intended; pick a scheme role.

6. Verify

./gradlew :app:testDebugUnitTest :app:assembleDebug

Then check by hand, because these are the things tests here do not catch:

• Dark theme, and dynamic colour on (Settings → ダイナミックカラー).
• The tab row in both positions (Settings → タブバーの配置), including the bottom one with a gesture-navigation bar.
• Swiping between card tabs — the header total must move with the swipe, not after it.
• A subscription whose card has been deleted (「不明なカード」), and a mixed-currency total.
• Large font scale, if the feature adds text.

If the change touches reminders, also check what tests cannot: set a reminder a couple of minutes out, confirm it arrives, and confirm the next one is still booked afterwards. Then revoke the notification permission in system settings and come back — the Settings screen should say so, and granting it again should start reminders working without a restart. .claude/rules/reminders.md explains why each of those is a distinct failure mode.

7. Write it down

If the feature changes an architectural rule, update CLAUDE.md or the relevant file in .claude/rules/. Add a CHANGELOG.md entry, and if it lands something from docs/roadmap.md, tick it off there.