kotlin-project-bugfix
starsforks
How to install kotlin-project-bugfix?
mmiani/kotlin-kmp-claude-agent-skills/kotlin-project-bugfix
$npx -y skills add mmiani/kotlin-kmp-claude-agent-skills --skill kotlin-project-bugfixUse 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.
SKILL.md
| 1 | # Kotlin Project Bug Fix |
| 2 | |
| 3 | Use this skill when fixing an existing bug in a Kotlin Multiplatform project. |
| 4 | |
| 5 | This is a bug-fixing skill, not a feature-building skill and not a review-only skill. |
| 6 | |
| 7 | Your goal is to: |
| 8 | - identify the real root cause |
| 9 | - fix the bug with the smallest correct change |
| 10 | - avoid unrelated refactors |
| 11 | - preserve the current architecture unless the bug proves the design is wrong |
| 12 | - prevent regressions with targeted tests where appropriate |
| 13 | |
| 14 | Do not optimize for speed alone. |
| 15 | Optimize for correctness, stability, maintainability, and regression safety. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Core bug-fixing philosophy |
| 20 | |
| 21 | Do not patch symptoms before understanding the path that produces them. |
| 22 | |
| 23 | Always trace the bug across the full flow that could be involved: |
| 24 | - UI rendering |
| 25 | - state holder / ViewModel / presenter |
| 26 | - domain/business logic |
| 27 | - repository/data layer |
| 28 | - persistence/cache |
| 29 | - mapping between layers |
| 30 | - navigation/lifecycle/re-entry |
| 31 | - source-set/platform-specific behavior |
| 32 | - coroutine/flow/concurrency timing |
| 33 | |
| 34 | Prefer the smallest coherent fix that addresses the true cause. |
| 35 | |
| 36 | Do not refactor unrelated areas during bug fixing unless the refactor is necessary to safely fix the bug. |
| 37 | |
| 38 | --- |
| 39 | |
| 40 | ## Primary goals |
| 41 | |
| 42 | For every bug fix, optimize for: |
| 43 | |
| 44 | 1. **Root-cause correctness** |
| 45 | 2. **Minimal diff** |
| 46 | 3. **Preservation of architecture** |
| 47 | 4. **No unrelated cleanup** |
| 48 | 5. **Regression prevention** |
| 49 | 6. **Clear state/model boundary handling** |
| 50 | 7. **KMP source-set correctness** |
| 51 | 8. **Compose/lifecycle correctness** |
| 52 | 9. **Coroutine/cancellation/concurrency correctness** |
| 53 | 10. **Persistence/re-entry safety** |
| 54 | 11. **Security/privacy safety where relevant** |
| 55 | 12. **Testability** |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## Required workflow |
| 60 | |
| 61 | Follow this workflow unless explicitly told otherwise. |
| 62 | |
| 63 | ### Step 1: Classify the bug |
| 64 | First classify the bug. A bug may involve more than one category. |
| 65 | |
| 66 | Possible categories: |
| 67 | - UI/layout bug |
| 68 | - design-system integration bug |
| 69 | - state-management bug |
| 70 | - ViewModel/presenter orchestration bug |
| 71 | - business-logic bug |
| 72 | - mapper/model-boundary bug |
| 73 | - persistence/cache/reload bug |
| 74 | - navigation/back-stack bug |
| 75 | - lifecycle/re-entry bug |
| 76 | - coroutine/flow/cancellation bug |
| 77 | - concurrency/race-condition bug |
| 78 | - platform-specific bug |
| 79 | - backend-contract/parsing bug |
| 80 | - permissions/session/auth bug |
| 81 | |
| 82 | ### Step 2: Inspect before editing |
| 83 | Before changing code, inspect the end-to-end path relevant to the bug. |
| 84 | |
| 85 | At minimum inspect: |
| 86 | - screen/composable(s) involved |
| 87 | - state holder / ViewModel / presenter |
| 88 | - relevant UI models |
| 89 | - domain/use-case logic if present |
| 90 | - repository/data source path if relevant |
| 91 | - persistence/storage/entity/DTO models if relevant |
| 92 | - mappers between storage/domain/UI if relevant |
| 93 | - navigation/lifecycle/re-entry behavior if relevant |
| 94 | - source-set placement if any platform-specific code is involved |
| 95 | - existing tests around the affected flow |
| 96 | |
| 97 | Do not jump to a UI-only fix if the bug may come from state, mapping, persistence, or lifecycle. |
| 98 | |
| 99 | ### Step 3: Diagnose root-cause candidates |
| 100 | Before implementing, produce a short diagnosis: |
| 101 | 1. observed behavior |
| 102 | 2. expected behavior |
| 103 | 3. likely root-cause candidates |
| 104 | 4. layers involved |
| 105 | 5. files likely to change |
| 106 | 6. chosen fix strategy |
| 107 | 7. risks / edge cases |
| 108 | |
| 109 | If multiple causes are plausible, choose the most evidence-based one and verify it against the code. |
| 110 | |
| 111 | ### Step 4: Implement the smallest correct fix |
| 112 | Apply only the changes needed to fix the bug safely. |
| 113 | |
| 114 | Prefer: |
| 115 | - fixing the root cause instead of masking the symptom |
| 116 | - extracting a small mapper/helper only if needed |
| 117 | - preserving existing public APIs unless change is required |
| 118 | - keeping the diff easy to review |
| 119 | |
| 120 | ### Step 5: Add regression protection |
| 121 | Where appropriate, add or update tests for: |
| 122 | - pure bug-triggering logic |
| 123 | - mapper/model conversion issues |
| 124 | - state transitions |
| 125 | - repository coordination |
| 126 | - parsing/serialization issues |
| 127 | - concurrency-sensitive behavior |
| 128 | |
| 129 | Do not add noisy tests for trivial wiring. |
| 130 | |
| 131 | --- |
| 132 | |
| 133 | ## Root-cause rules by bug type |
| 134 | |
| 135 | ### UI/layout bugs |
| 136 | For layout, keyboard, scrolling, spacing, visibility, clipping, or overlapping issues: |
| 137 | - inspect insets handling before adding padding |
| 138 | - inspect scaffold/content padding |
| 139 | - inspect duplicate `imePadding`, `navigationBarsPadding`, or bottom padding |
| 140 | - inspect list content padding vs composer/input bar spacing |
| 141 | - inspect scroll state ownership |
| 142 | - inspect whether the bug happens only on first entry, re-entry, or keyboard transitions |
| 143 | - inspect whether state timing is causing the UI symptom |
| 144 | |
| 145 | Do not assume the UI layout is the sole cause if the issue appears after navigation or re-entry. |
| 146 | |
| 147 | ### State-management bugs |
| 148 | For wrong loading/error/success behavior, stale content, impossible states, or wrong transient effects: |
| 149 | - inspect state ownership |
| 150 | - inspect |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
