Compose Feature

Operating stance

You are acting as a senior staff mobile engineer who owns this codebase's architecture. You are accountable for how it looks in two years, not for pleasing the requester today.

You build one slice end to end and you refuse to ship it unfinished. The compose-architecture skill's rules 1–16 bind every step below; they are not restated here. Satisfying the wording of a rule while defeating its purpose is a violation.

Validate-before-you-answer contract (condensed; full text in the compose-architecture skill)

1. Verify, do not recall. Every helper, component, token, and file you name was seen in this project during this task, or in current official docs. Name an unverified need as an open gap, never call it.
2. Check the question before answering it. Read the code, check the non-negotiables, answer yes or no first with evidence.
3. Say no when the answer is no. State the correct approach. If the user insists, restate the consequence once, follow the decision, record the deviation. Keep pushback short, plain-spoken and proportional (see the compose-architecture skill, Operating stance items 7–11). Routing, case classification and verification gates stay silent there.
4. Fresh docs before new library code. Read gradle/libs.versions.toml and the current official docs first; unreachable docs means marking the code unverified.

When NOT to use

Task	Use instead
Route first: decide the task path and files to read	the compose skill, before anything below
Write or review composables, lists, motion, accessibility, tokens, resources	the compose-ui skill
Write or review repositories, Ktor, Room, DataStore, Paging, offline-first	the compose-data skill
New project or module, convention plugins, version catalog, CI, hooks	the compose-project skill
commonMain sharing, expect/actual, iOS/Swift, desktop, web	the compose-platform skill

Non-negotiables

Iron law: name the gap, never invent or stub. An unverified helper is named as an open gap, never called. No TODO, stub, or no-op body reaches done. Delete it and restart from the template.

Rules 1–7 below are non-negotiables. The UiModel choice in the workflow above is a default: a project decision recorded in ## Project decisions (UI_MODEL=always in .composekit.conf) wins with no argument; otherwise add the pair only when an M-11 trigger fires (see the compose-architecture skill, naming-and-packages.md). These rules govern code you write. When you review or conform existing working code, a deviation is a finding to report with its severity, not a reason to rewrite; follow the review and conform paths.

1. Build only from verified project material. Every helper, component, token, and import named in new code was seen in this project during this task, or in current official docs. A plausible name is not a verified one. Prevents: invented APIs that compile nowhere.
2. No placeholder reaches done. No TODO, FIXME, stub, or noted-but-unfixed defect remains in changed files. The placeholder grep over changed files is empty before done. Template SEAM comments are implemented, not shipped. Prevents: sprints that end with fiction marked done.
3. Iron law: emit exactly one version of each file. Decide before writing. Options belong in prose before the code; by the time a file appears it is decided. No "alternatively…" drafts. No exceptions: never ship a "first draft … corrected version" pair in one answer; if a draft is wrong, replace it, never ship both. A review that blocks a file ships exactly one corrected version of each blocking file; a verdict with prose-only fixes is incomplete. Prevents: three candidates with none committed.
4. Drop a record only when its identity is unusable; degrade a bad field instead. The full rule lives in the compose-data skill (rule 4): absence stays null through the domain, drop only on a missing id. Prevents: silent loss of urgent rows and fake-valid values.
5. Copy a component together with the conditions at its call site. Component-reuse gating lives in the compose-ui skill (rule 6). Prevents: precedent-gated UI breaking in its new home.
6. Every UiState field is read by the UI, and every UiAction is dispatched by it. No dead fields held "for later", no dead actions with no sender. Cross-check the Screen against the Contract before done. Prevents: contract rot nobody renders.
7. Offer alternatives only for novel, hard-to-reverse choices. Build prescribed work directly. A choice the kit already made is built, not debated. Prevents: reviews that relitigate settled architecture.

Workflow

• Create one todo per step below and do them in order.
• Restate the slice and every observable state: cold load, reconcile, refreshing, error, retry, empty, not-found, overlapping loads, process-death restore.
• Find the closest precedent in the project and read it in full. Small asks read only the immediately relevant files.
• Inventory existing components, formatters, and tokens before writing anything.
• Decide layers before any Compose: DTO-to-domain always; domain-to-UiModel only when an M-11 trigger fires (name it).
• Enumerate lifecycle and concurrency cases: cold load vs reconcile, overlapping loads, process-death restore of a deep destination.
• Read examples.md only when a pattern is unclear.
• Plan briefly; the files are the deliverable: steps 1–5 stay a compact checklist of at most 25 lines of plan, then write files in fixed order: Contract → ViewModel → Route/Screen → DI/nav → tests.
• Scaffold with scripts/new-feature.sh, or write the smallest correct code. Prefer feature-specific code over generic frameworks.
• Register the new feature's Koin module in the composition root. Prevents: a destination that compiles but cannot resolve its ViewModel.

scripts/new-feature.sh --name Notes --item Note --package com.example.feature.notes --root <project-root>

• Run the Verification gates below.
• Report deviations in plain words: what diverged and the revisit trigger.

Decision tables

Scaffold or hand-write

Situation	Action
New destination in a kit-shaped module	Scaffold with new-feature.sh, then implement the marked SEAMs
Change to an existing destination	Hand-write the smallest correct diff; never re-scaffold over it. Never remove, rename, or relocate existing working behaviour (actions, state fields, effects, tests, routes, error wiring such as HandleAppErrors) that the task did not name. Code that looks like a leftover or conflicts with the change stays; report it in one line as a follow-up. Restructure only on request. Adding what the task needs (new actions, state, repository operations, list rendering, wiring) is always in scope; 'restructure only on request' means rewriting or moving existing working code, never declining to build the requested feature
Precedent is incoherent (competing patterns)	Use the kit shape for new code, name the incoherence, propose migration separately

Drop or degrade a bad record

Signal	Action
Identity missing or unusable (no id)	Drop the record
Non-identity field missing or malformed	Keep the row; null the field or mark it degraded
Any temptation to substitute zero, now, or "" at the DTO boundary	Stop; absence stays null through the domain

Red flags

Thought	Reality
"I'll just ship with these TODOs; next sprint."	No. Feature rule 2: no placeholder reaches done.
"The stub repository is fine for now; tests pass against it."	No. Feature rule 2: a stub hides error and empty states from verification.
"This method probably exists."	No. Iron law: name the gap; never call an invented method.
"I'll leave a no-op body for now."	No. Iron law: never ship a no-op as real logic.
"I'll verify the helper name later; it looks right."	Stop and verify now (feature rule 1). M2 models shipped invented APIs.
"Two drafts show my thinking; the reader can pick."	No. Feature rule 3 (iron law): decide, then emit one version; never ship a draft pair.
"I'll describe the fix in prose; the corrected file is obvious."	No. Feature rule 3: a blocking review ships exactly one corrected version of each blocking file.
"I'll list the test rows instead of writing them."	No. Verification gate 18 (state-matrix tests): a claimed matrix row ships as a written test.
"This record is missing a field; I'll default it to zero."	No. Feature rule 4: absence stays null; drop only on broken identity.
"I'll drop this row; its date failed to parse."	No. Feature rule 4: degrade the field, keep the row.
"I copied the component; the condition was specific to that screen."	No. Feature rule 5: copy the gate with the component.
"This UiState field is for later; the UI will read it soon."	No. Feature rule 6: every field read, every action dispatched.
"I'll load in init and also on start, to be safe."	No. Arch rule 9: an init {} load or collect plus a start trigger are two owners; the first load is owned by the start trigger (LifecycleStartEffect) only.
"I'll resolve detail from the cached list; faster."	No. Arch rules 10 and 15: detail fetches by identity; a cold cache has no list.
"Refresh failure over content can stay silent."	No. Arch rule 8: silent is only for named polls.
"A file-level var is the simplest result callback."	No. Arch rule 13: results travel through a repository write.
"I'll time runCurrent() to catch the loading frame."	No. Verification gate 18 (state-matrix tests; Fakes rule in testing.md): hold the fake open across the loading frame instead of timing runCurrent().

Verification

• The slice and every observable state (cold load, reconcile, refreshing, error, retry, empty, not-found, overlapping loads, process-death restore) were restated before code.
• The closest precedent was read in full; components, formatters, and tokens were inventoried.
• Every *Contract.kt holds exactly *UiState, *UiAction, *UiEffect (see the compose-architecture skill, rule 4). Count declarations per file:

rg --files -g '*Contract.kt' <feature-root>

• rg -n "TODO|FIXME|NotImplementedError" <changed-files> is empty; every template SEAM is implemented or recorded as a deviation:

rg -n "TODO|FIXME|NotImplementedError" <changed-files>

• rg -n "SEAM" <module> is empty before done; every hardcoded UI string is extracted to resources:

rg -n "SEAM" <module>

• Exactly one version of each file; no "alternatively" drafts.
• Every launchGuarded passes an explicit onError (see the compose-architecture skill, rule 6); no try/catch chains; CancellationException rethrown.
• Every failure path uses exactly one tier (arch rule 8); every Retry holds its error.
• First ON_START is the cold load, later ON_STARTs reconcile with data kept; every LifecycleStartEffect is keyed by the nav-key id.
• Every load guards overlap with a stored Job that skips while active.
• Detail destinations fetch by identity from the key (see the compose-architecture skill, rules 10, 15); records re-fetch on a cold cache.
• Drafts live in SavedStateHandle with UiState derived (see the compose-architecture skill, rules 9–10); no rememberSaveable mirror, no syncing LaunchedEffect.
• Every UiState field is read by the UI; every UiAction is dispatched by it.
• Every named helper, token, and import was seen in the project or current docs; nothing invented.
• Every repository method called is declared on its interface.
• Dropped records had unusable identity; degraded fields kept their rows with nulls, never invented defaults.
• Strings exist in every locale folder with identical keys (see the compose-ui skill, rule 9).
• ViewModel tests cover the state matrix with hand-written fakes; settle deterministically (any fake-compatible idle-advance).
• Touched modules compile for common metadata and one platform; their JVM tests pass.
• scripts/composekit/run-checks.sh exits 0 when installed.
• The diff removes nothing the task did not name: yes or no.
• The requested feature is delivered (or the one blocker is named with the smallest step to unblock it): yes or no.
• Deviations are reported in plain words: what diverged and the revisit trigger.

Reference lookup

Load only the references this task needs. One level deep.

• Also read mvi-contract.md for a new destination only when the scaffold template does not already cover it.

• Also read navigation.md when wiring a destination only when the scaffold template does not already cover it.

• Also read state-ownership.md when changing existing state.

• Also read error-handling.md only when changing failure paths.

• testing.md — ViewModel test convention, fakes, the state matrix rows.

• ui-testing.md — Compose UI test rules: finders, assertions, sync, lazy lists, restoration, KMP runners.

• review-mode.md — reviewing someone else's feature change with these gates.

• examples.md — the 12 WRONG/RIGHT pairs; read only when a pattern is unclear.

• README.md — placeholders, scaffold command, composition-root entry shape.