Use when diagnosing and fixing bugs in a Kotlin Multiplatform project. Focus on root-cause analysis, minimal safe fixes, KMP correctness, UI/state/data/persistence/concurrency issues, and regression prevention.
Instrucciones de origen · Vista previa de solo lectura
name
kotlin-project-bugfix
description
Use when diagnosing and fixing bugs in a Kotlin Multiplatform project. Focus on root-cause analysis, minimal safe fixes, KMP correctness, UI/state/data/persistence/concurrency issues, and regression prevention.
license
Apache-2.0
metadata
{"author":"Mariano Miani","version":"1.0.0"}
Kotlin Project Bug Fix
Use this skill when fixing an existing bug in a Kotlin Multiplatform project.
This is a bug-fixing skill, not a feature-building skill and not a review-only skill.
Your goal is to:
identify the real root cause
fix the bug with the smallest correct change
avoid unrelated refactors
preserve the current architecture unless the bug proves the design is wrong
prevent regressions with targeted tests where appropriate
Do not optimize for speed alone.
Optimize for correctness, stability, maintainability, and regression safety.
Core bug-fixing philosophy
Do not patch symptoms before understanding the path that produces them.
Always trace the bug across the full flow that could be involved:
UI rendering
state holder / ViewModel / presenter
domain/business logic
repository/data layer
persistence/cache
mapping between layers
navigation/lifecycle/re-entry
source-set/platform-specific behavior
coroutine/flow/concurrency timing
Prefer the smallest coherent fix that addresses the true cause.
Do not refactor unrelated areas during bug fixing unless the refactor is necessary to safely fix the bug.
Primary goals
For every bug fix, optimize for:
Root-cause correctness
Minimal diff
Preservation of architecture
No unrelated cleanup
Regression prevention
Clear state/model boundary handling
KMP source-set correctness
Compose/lifecycle correctness
Coroutine/cancellation/concurrency correctness
Persistence/re-entry safety
Security/privacy safety where relevant
Testability
Required workflow
Follow this workflow unless explicitly told otherwise.
Step 1: Classify the bug
First classify the bug. A bug may involve more than one category.
Possible categories:
UI/layout bug
design-system integration bug
state-management bug
ViewModel/presenter orchestration bug
business-logic bug
mapper/model-boundary bug
persistence/cache/reload bug
navigation/back-stack bug
lifecycle/re-entry bug
coroutine/flow/cancellation bug
concurrency/race-condition bug
platform-specific bug
backend-contract/parsing bug
permissions/session/auth bug
Step 2: Inspect before editing
Before changing code, inspect the end-to-end path relevant to the bug.
At minimum inspect:
screen/composable(s) involved
state holder / ViewModel / presenter
relevant UI models
domain/use-case logic if present
repository/data source path if relevant
persistence/storage/entity/DTO models if relevant
mappers between storage/domain/UI if relevant
navigation/lifecycle/re-entry behavior if relevant
source-set placement if any platform-specific code is involved
existing tests around the affected flow
Do not jump to a UI-only fix if the bug may come from state, mapping, persistence, or lifecycle.
Step 3: Diagnose root-cause candidates
Before implementing, produce a short diagnosis:
observed behavior
expected behavior
likely root-cause candidates
layers involved
files likely to change
chosen fix strategy
risks / edge cases
If multiple causes are plausible, choose the most evidence-based one and verify it against the code.
Step 4: Implement the smallest correct fix
Apply only the changes needed to fix the bug safely.
Prefer:
fixing the root cause instead of masking the symptom
extracting a small mapper/helper only if needed
preserving existing public APIs unless change is required
keeping the diff easy to review
Step 5: Add regression protection
Where appropriate, add or update tests for:
pure bug-triggering logic
mapper/model conversion issues
state transitions
repository coordination
parsing/serialization issues
concurrency-sensitive behavior
Do not add noisy tests for trivial wiring.
Root-cause rules by bug type
UI/layout bugs
For layout, keyboard, scrolling, spacing, visibility, clipping, or overlapping issues:
inspect insets handling before adding padding
inspect scaffold/content padding
inspect duplicate imePadding, navigationBarsPadding, or bottom padding
inspect list content padding vs composer/input bar spacing
inspect scroll state ownership
inspect whether the bug happens only on first entry, re-entry, or keyboard transitions
inspect whether state timing is causing the UI symptom
Do not assume the UI layout is the sole cause if the issue appears after navigation or re-entry.
State-management bugs
For wrong loading/error/success behavior, stale content, impossible states, or wrong transient effects:
inspect state ownership
inspect whether one-time effects are mixed into persistent state
inspect whether multiple async paths can mutate the same state inconsistently
inspect stale response handling
inspect whether UI is deriving too much logic locally
Prefer explicit state transitions over ad hoc boolean combinations.
Mapper/model-boundary bugs
If data displays correctly initially but breaks after reload/re-entry:
inspect storage model
inspect serialization/deserialization
inspect entity ↔ domain ↔ UI mapping
inspect whether transient in-memory fields are incorrectly required for rendering
inspect whether content type is inferred from text instead of modeled explicitly
If a persisted rich-content item becomes plain text later, treat that as a model/mapping bug first, not a UI bug.
Persistence/re-entry bugs
If a bug appears after:
navigating away and back
screen recreation
process recreation
retry/reload
app restart
Then inspect persistence/cache/source-of-truth behavior before changing UI rendering.
Be explicit about:
source of truth
reload path
mapper behavior on restored data
stale cache behavior
local vs remote precedence
Coroutine/flow/cancellation bugs
If the bug involves loading stuck forever, duplicate events, missing updates, or inconsistent async behavior:
inspect coroutine scope ownership
inspect cancellation handling
inspect catch / runCatching
inspect StateFlow / SharedFlow usage
inspect duplicate collectors
inspect race conditions between refresh, send, retry, and navigation
Do not swallow CancellationException.
Do not fix timing bugs with brittle arbitrary delays unless absolutely unavoidable.
Concurrency/race-condition bugs
If the bug depends on timing or overlapping actions:
inspect repeated taps
inspect duplicate submissions
inspect stale responses overriding fresh state
inspect multiple jobs writing to the same state
inspect whether latest-wins / first-wins behavior is defined
inspect scroll-after-update timing carefully in chat/list UIs
Navigation/lifecycle bugs
If behavior changes on re-entry, deep link entry, back navigation, or app resume:
inspect route arguments
inspect state restoration
inspect screen recreation behavior
inspect whether the state holder is recreated unexpectedly
inspect whether lifecycle-side effects run too often or not enough
Platform-specific bugs
If the bug may differ between Android and iOS:
verify whether the logic belongs in shared code or platform code
