understanding-hot-reload-limits

Name: understanding-hot-reload-limits
Author: skydoves

454stars15forks

How to install understanding-hot-reload-limits?

skydoves/compose-performance-skills/understanding-hot-reload-limits

$npx -y skills add skydoves/compose-performance-skills --skill understanding-hot-reload-limits

Installs into the current project.

Summary

Use this skill to teach Claude exactly which Kotlin and Compose changes hot-reload under Compose HotSwan and which trigger a full incremental rebuild fallback. Root cause is Android Runtime (ART) class schema immutability; only method bodies are mutable at runtime, so any change

Files · 1

View on GitHub

SKILL.md

1	# Understanding Hot Reload Limits: stay inside the fast path
2
3	Android Runtime (ART) enforces strict rules for class redefinition: a redefined class must have an identical schema (fields, method signatures, interfaces) as the previous version. Only method bodies are mutable at runtime. HotSwan automatically detects schema changes and falls back to a full incremental build, so failures are not silent. Knowing the boundary in advance is what keeps an iteration loop sub-second instead of multi-second.
4
5	## When to use this skill
6
7	- The developer asks "why did this trigger a full rebuild?", "why isn't this hot reloading?", or "what does HotSwan support?".
8	- A PR review surfaces a refactor (parameter change, constructor change, interface extraction, new resource id) that would push a hot-reload session into a rebuild.
9	- The developer is planning a session and wants to order edits so the slow ones happen at the end.
10	- The developer reports an `inline fun` change that "didn't reload" and is debugging.
11
12	## When NOT to use this skill
13
14	- Setup or first-run troubleshooting. See `../setting-up-compose-hotswan/SKILL.md`.
15	- Pure state-preservation question (the reload happened but state was lost). See the state-preservation sibling skill.
16	- Configuration of the AI iteration loop or MCP server. See the AI-loop sibling skill.
17
18	## Prerequisites
19
20	- HotSwan installed and verified per `../setting-up-compose-hotswan/SKILL.md` (tool window status `WATCHING`, body-only edit reloads in under one second).
21	- Familiarity with the Kotlin compiler's distinction between method-body changes and class-schema changes.
22
23	## Boundary tables
24
25	### Hot-reloadable (no rebuild)
26
27	\| Change \| Notes \|
28	\|---\|---\|
29	\| Composable function body \| text, colors, modifiers, layout, control flow inside the function \|
30	\| Non-composable function body \| ViewModel methods, mappers, utilities, repositories \|
31	\| Adding a new composable \| same file or new file \|
32	\| Reordering composables \| HotSwan 1.2.0+ \|
33	\| Resource value changes \| `strings.xml` value, `colors.xml` value, `dimens.xml` value \|
34	\| Extension functions \| including suspend, including vararg \|
35	\| Adding `data class` properties \| API 30+ only \|
36	\| Numeric, string, float literal patches \| compiled separately for fastest reload \|
37
38	### Forces full rebuild (fallback)
39
40	\| Change \| Reason \|
41	\|---\|---\|
42	\| Adding or removing function parameters \| method signature changes \|
43	\| Constructor changes \| parameter list, default values, init blocks affecting fields \|
44	\| Interface or superclass changes \| class hierarchy is part of the schema \|
45	\| Adding new resource ids \| new `R.string`, `R.drawable`, `R.id` entries require generated `R` class regeneration \|
46	\| Inline functions \| expanded at every call site; no discrete unit to swap \|
47	\| Lambda count change inside a function \| internal lambda class renumbering \|
48	\| Removing a previously defined function \| method table shrinks; schema changes \|
49	\| Adding `data class` properties below API 30 \| constructor schema change without ART support \|
50
51	## Workflow when a change does not hot-reload
52
53	1. Watch the HotSwan tool window status at the moment of save. A schema change surfaces as a "falling back to incremental build" status. That is the explicit signal, not a silent failure.
54	2. Read the change diff. Decide: is this a body-only change, or a schema change (signature, constructor, interface, field, new resource id, inline body, lambda count)?
55	3. If a refactor must change a signature, batch it. First make the body-only changes that get the screen to a working visual state and hot-reload them. Then, in a separate save, change the signature and accept the rebuild as the last step of the session.
56	4. For inline functions, drop `inline` for the duration of iteration. Refactor the function out of `inline` while iterating, hot-reload as needed, and restore `inline` before commit. If iteration is r

People who liked this also viewed

6 picks

Type

understanding-hot-reload-limits

454stars15forks

View on GitHub

How to install understanding-hot-reload-limits?

skydoves/compose-performance-skills/understanding-hot-reload-limits

$npx -y skills add skydoves/compose-performance-skills --skill understanding-hot-reload-limits

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Understanding Hot Reload Limits: stay inside the fast path
2
3	Android Runtime (ART) enforces strict rules for class redefinition: a redefined class must have an identical schema (fields, method signatures, interfaces) as the previous version. Only method bodies are mutable at runtime. HotSwan automatically detects schema changes and falls back to a full incremental build, so failures are not silent. Knowing the boundary in advance is what keeps an iteration loop sub-second instead of multi-second.
4
5	## When to use this skill
6
7	- The developer asks "why did this trigger a full rebuild?", "why isn't this hot reloading?", or "what does HotSwan support?".
8	- A PR review surfaces a refactor (parameter change, constructor change, interface extraction, new resource id) that would push a hot-reload session into a rebuild.
9	- The developer is planning a session and wants to order edits so the slow ones happen at the end.
10	- The developer reports an `inline fun` change that "didn't reload" and is debugging.
11
12	## When NOT to use this skill
13
14	- Setup or first-run troubleshooting. See `../setting-up-compose-hotswan/SKILL.md`.
15	- Pure state-preservation question (the reload happened but state was lost). See the state-preservation sibling skill.
16	- Configuration of the AI iteration loop or MCP server. See the AI-loop sibling skill.
17
18	## Prerequisites
19
20	- HotSwan installed and verified per `../setting-up-compose-hotswan/SKILL.md` (tool window status `WATCHING`, body-only edit reloads in under one second).
21	- Familiarity with the Kotlin compiler's distinction between method-body changes and class-schema changes.
22
23	## Boundary tables
24
25	### Hot-reloadable (no rebuild)
26
27	\| Change \| Notes \|
28	\|---\|---\|
29	\| Composable function body \| text, colors, modifiers, layout, control flow inside the function \|
30	\| Non-composable function body \| ViewModel methods, mappers, utilities, repositories \|
31	\| Adding a new composable \| same file or new file \|
32	\| Reordering composables \| HotSwan 1.2.0+ \|
33	\| Resource value changes \| `strings.xml` value, `colors.xml` value, `dimens.xml` value \|
34	\| Extension functions \| including suspend, including vararg \|
35	\| Adding `data class` properties \| API 30+ only \|
36	\| Numeric, string, float literal patches \| compiled separately for fastest reload \|
37
38	### Forces full rebuild (fallback)
39
40	\| Change \| Reason \|
41	\|---\|---\|
42	\| Adding or removing function parameters \| method signature changes \|
43	\| Constructor changes \| parameter list, default values, init blocks affecting fields \|
44	\| Interface or superclass changes \| class hierarchy is part of the schema \|
45	\| Adding new resource ids \| new `R.string`, `R.drawable`, `R.id` entries require generated `R` class regeneration \|
46	\| Inline functions \| expanded at every call site; no discrete unit to swap \|
47	\| Lambda count change inside a function \| internal lambda class renumbering \|
48	\| Removing a previously defined function \| method table shrinks; schema changes \|
49	\| Adding `data class` properties below API 30 \| constructor schema change without ART support \|
50
51	## Workflow when a change does not hot-reload
52
53	1. Watch the HotSwan tool window status at the moment of save. A schema change surfaces as a "falling back to incremental build" status. That is the explicit signal, not a silent failure.
54	2. Read the change diff. Decide: is this a body-only change, or a schema change (signature, constructor, interface, field, new resource id, inline body, lambda count)?
55	3. If a refactor must change a signature, batch it. First make the body-only changes that get the screen to a working visual state and hot-reload them. Then, in a separate save, change the signature and accept the rebuild as the last step of the session.
56	4. For inline functions, drop `inline` for the duration of iteration. Refactor the function out of `inline` while iterating, hot-reload as needed, and restore `inline` before commit. If iteration is r

People who liked this also viewed

6 picks

Type