kotlin-kmp-refactor-safety

Name: kotlin-kmp-refactor-safety
Author: mmiani

56stars5forks

How to install kotlin-kmp-refactor-safety?

mmiani/kotlin-kmp-claude-agent-skills/kotlin-kmp-refactor-safety

$npx -y skills add mmiani/kotlin-kmp-claude-agent-skills --skill kotlin-kmp-refactor-safety

Installs into the current project.

Summary

Refactor discipline for existing codebases. Enforces scope control, migration safety, compatibility, observability, and tests to keep refactors reviewable and low-risk.

Files · 1

View on GitHub

SKILL.md

1	# KMP Refactor Safety Skill
2
3	Use this skill when the task is primarily a refactor, migration, reliability hardening, or architectural cleanup of existing code (not a greenfield feature).
4	This skill is about change discipline and reviewability, not system architecture itself. Pair it with your architecture/style/testing skills as needed.
5
6	## Primary objective
7
8	Deliver refactors that are:
9	- minimal in surface area
10	- safe to review and merge
11	- free of parallel/competing implementations
12	- regression-resistant (tests + observability)
13
14	## Non-negotiables
15
16	### 1) Scope control (no opportunistic rewrites)
17	- Touch only files required to achieve the goal.
18	- Do not reformat, rename, or “clean up” unrelated code.
19	- Avoid broad mechanical changes unless explicitly requested.
20	- Keep diffs small and intention-revealing.
21
22	### 2) No parallel implementations
23	- Do not introduce a new pattern while leaving the old pattern active.
24	- End state must be one of:
25	- old path removed, OR
26	- old path gated behind a feature flag with a clear removal plan (explicit TODO + tracking issue).
27	- Avoid duplicate sources of truth. If ownership must move, move it once and rewire callers deterministically.
28
29	### 3) Preserve public contracts unless required
30	- Keep public APIs stable (interfaces, model shapes, routing/public endpoints, configuration surface).
31	- If a contract must change:
32	- update all call sites in the same change-set
33	- document the breaking change in PR notes/release notes
34	- add targeted tests proving compatibility and intent
35
36	### 4) Refactor in safe phases
37	Prefer this order:
38	1. Foundation: introduce the new core abstraction (e.g., manager/store/service) and wire it without changing behavior.
39	2. Adoption: migrate existing call sites incrementally to the new abstraction.
40	3. Lock-in: remove the old path or gate it behind a flag (default off) and make the new path the default.
41	4. Cleanup: delete dead code, consolidate configuration, reduce complexity.
42
43	Never ship an ambiguous half-state where both old and new paths may run without a flag and clear routing.
44
45	### 5) Observability (redacted)
46	For flows prone to edge cases (auth, payments, retries, background/foreground, webhooks, state restoration):
47	- add logs/metrics around transitions and decisions
48	- never log secrets (tokens, passwords, codes, personal data)
49	- log only:
50	- booleans/branch decisions
51	- status codes and operation names
52	- hashed or truncated IDs if needed (e.g., last 4 chars)
53	- ensure logs can be disabled or are appropriate for production environments
54
55	### 6) Tests are part of the refactor
56	Minimum expectations:
57	- unit tests for pure logic/state transitions/mappers
58	- regression tests for the bug or failure mode motivating the refactor
59	- coverage for:
60	- success path
61	- failure path
62	- concurrency/race behavior when applicable (mutex, retry, idempotency)
63	- avoid brittle tests; prefer deterministic inputs/outputs and stable assertions
64
65	### 7) Idempotency and re-entrancy for callbacks
66	For events that can repeat (callbacks, deep links, webhooks, background resume):
67	- handle duplicates safely
68	- validate inputs before side effects
69	- operations should be safe to retry without corrupting state
70
71	### 8) Backwards compatibility and migration safety
72	- Use versioning or feature flags for behavior changes that might break existing users.
73	- Provide migration steps (data migrations, config updates) in a single place.
74	- If data shape changes:
75	- define transitional support window
76	- ensure rollback strategy (or non-destructive migrations)
77
78	### 9) Performance and resource safety
79	- Avoid adding disk/network reads on hot paths (e.g., per-request storage reads).
80	- Prefer caching with explicit invalidation when correctness requires it.
81	- Ensure retries are bounded (max 1 retry unless specified) and do not create loops.
82
83	### 10) PR hygiene (reviewable output)
84	- Prefer small, coherent commits with clear messages.
85	- Avoid reordering code blocks unless necessary.
86	- Include PR notes:
87	- What changed
88	- Why
89	- How to test
90	- Flags/migration steps
91	- Rollback plan (if relevant)
92
93	## Quick refactor checklist
94	- [ ] Single source of truth after refactor
95	- [ ] No stale in-memory state alongside persisted state (unless intentionally synchronized)
96	- [ ] No competing interceptors/validators/plugins that overwrite each other
97	- [ ] Duplicate events/callbacks are handled idempotently
98	- [ ] Failure modes are explicit and do not cause silent data loss/logouts
99	- [ ] Tests cover the motivating regression and key edge cases
100	- [ ] Clear migration/flag/rollback notes included

People who liked this also viewed

6 picks

Type

kotlin-kmp-refactor-safety

56stars5forks

View on GitHub

How to install kotlin-kmp-refactor-safety?

mmiani/kotlin-kmp-claude-agent-skills/kotlin-kmp-refactor-safety

$npx -y skills add mmiani/kotlin-kmp-claude-agent-skills --skill kotlin-kmp-refactor-safety

Installs into the current project.

Summary

Refactor discipline for existing codebases. Enforces scope control, migration safety, compatibility, observability, and tests to keep refactors reviewable and low-risk.

Files · 1

View on GitHub

SKILL.md

1	# KMP Refactor Safety Skill
2
3	Use this skill when the task is primarily a refactor, migration, reliability hardening, or architectural cleanup of existing code (not a greenfield feature).
4	This skill is about change discipline and reviewability, not system architecture itself. Pair it with your architecture/style/testing skills as needed.
5
6	## Primary objective
7
8	Deliver refactors that are:
9	- minimal in surface area
10	- safe to review and merge
11	- free of parallel/competing implementations
12	- regression-resistant (tests + observability)
13
14	## Non-negotiables
15
16	### 1) Scope control (no opportunistic rewrites)
17	- Touch only files required to achieve the goal.
18	- Do not reformat, rename, or “clean up” unrelated code.
19	- Avoid broad mechanical changes unless explicitly requested.
20	- Keep diffs small and intention-revealing.
21
22	### 2) No parallel implementations
23	- Do not introduce a new pattern while leaving the old pattern active.
24	- End state must be one of:
25	- old path removed, OR
26	- old path gated behind a feature flag with a clear removal plan (explicit TODO + tracking issue).
27	- Avoid duplicate sources of truth. If ownership must move, move it once and rewire callers deterministically.
28
29	### 3) Preserve public contracts unless required
30	- Keep public APIs stable (interfaces, model shapes, routing/public endpoints, configuration surface).
31	- If a contract must change:
32	- update all call sites in the same change-set
33	- document the breaking change in PR notes/release notes
34	- add targeted tests proving compatibility and intent
35
36	### 4) Refactor in safe phases
37	Prefer this order:
38	1. Foundation: introduce the new core abstraction (e.g., manager/store/service) and wire it without changing behavior.
39	2. Adoption: migrate existing call sites incrementally to the new abstraction.
40	3. Lock-in: remove the old path or gate it behind a flag (default off) and make the new path the default.
41	4. Cleanup: delete dead code, consolidate configuration, reduce complexity.
42
43	Never ship an ambiguous half-state where both old and new paths may run without a flag and clear routing.
44
45	### 5) Observability (redacted)
46	For flows prone to edge cases (auth, payments, retries, background/foreground, webhooks, state restoration):
47	- add logs/metrics around transitions and decisions
48	- never log secrets (tokens, passwords, codes, personal data)
49	- log only:
50	- booleans/branch decisions
51	- status codes and operation names
52	- hashed or truncated IDs if needed (e.g., last 4 chars)
53	- ensure logs can be disabled or are appropriate for production environments
54
55	### 6) Tests are part of the refactor
56	Minimum expectations:
57	- unit tests for pure logic/state transitions/mappers
58	- regression tests for the bug or failure mode motivating the refactor
59	- coverage for:
60	- success path
61	- failure path
62	- concurrency/race behavior when applicable (mutex, retry, idempotency)
63	- avoid brittle tests; prefer deterministic inputs/outputs and stable assertions
64
65	### 7) Idempotency and re-entrancy for callbacks
66	For events that can repeat (callbacks, deep links, webhooks, background resume):
67	- handle duplicates safely
68	- validate inputs before side effects
69	- operations should be safe to retry without corrupting state
70
71	### 8) Backwards compatibility and migration safety
72	- Use versioning or feature flags for behavior changes that might break existing users.
73	- Provide migration steps (data migrations, config updates) in a single place.
74	- If data shape changes:
75	- define transitional support window
76	- ensure rollback strategy (or non-destructive migrations)
77
78	### 9) Performance and resource safety
79	- Avoid adding disk/network reads on hot paths (e.g., per-request storage reads).
80	- Prefer caching with explicit invalidation when correctness requires it.
81	- Ensure retries are bounded (max 1 retry unless specified) and do not create loops.
82
83	### 10) PR hygiene (reviewable output)
84	- Prefer small, coherent commits with clear messages.
85	- Avoid reordering code blocks unless necessary.
86	- Include PR notes:
87	- What changed
88	- Why
89	- How to test
90	- Flags/migration steps
91	- Rollback plan (if relevant)
92
93	## Quick refactor checklist
94	- [ ] Single source of truth after refactor
95	- [ ] No stale in-memory state alongside persisted state (unless intentionally synchronized)
96	- [ ] No competing interceptors/validators/plugins that overwrite each other
97	- [ ] Duplicate events/callbacks are handled idempotently
98	- [ ] Failure modes are explicit and do not cause silent data loss/logouts
99	- [ ] Tests cover the motivating regression and key edge cases
100	- [ ] Clear migration/flag/rollback notes included

People who liked this also viewed

6 picks

Type