understanding-hot-reload-limits

name	understanding-hot-reload-limits
description	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 to fields, signatures, constructors, interfaces, inline functions, or new resource ids forces a rebuild. Covers the supported-changes table, the rebuild-forcing list, the diff-then-batch workflow that keeps a hot-reload session inside the fast path, and the inline-function and new-resource-id pitfalls. Trigger when the user asks "why did this rebuild?", "why isn't this hot reloading?", wants to learn HotSwan's boundaries before adopting it, or when reviewing a refactor that risks pushing a hot-reload session into a full rebuild.
license	Apache-2.0. See LICENSE for complete terms.
metadata	{"author":"Jaewoong Eum (skydoves)","keywords":["jetpack-compose","performance","hot-reload","hotswan","art","class-redefinition","iteration","developer-experience"]}

Understanding Hot Reload Limits: stay inside the fast path

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.

When to use this skill

• The developer asks "why did this trigger a full rebuild?", "why isn't this hot reloading?", or " what does HotSwan support?".
• 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.
• The developer is planning a session and wants to order edits so the slow ones happen at the end.
• The developer reports an inline fun change that "didn't reload" and is debugging.

When NOT to use this skill

• Setup or first-run troubleshooting. See ../setting-up-compose-hotswan/SKILL.md.
• Pure state-preservation question (the reload happened but state was lost). See the state-preservation sibling skill.
• Configuration of the AI iteration loop or MCP server. See the AI-loop sibling skill.

Prerequisites

• HotSwan installed and verified per ../setting-up-compose-hotswan/SKILL.md (tool window status WATCHING, body-only edit reloads in under one second).
• Familiarity with the Kotlin compiler's distinction between method-body changes and class-schema changes.

Boundary tables

Hot-reloadable (no rebuild)

Change	Notes
Composable function body	text, colors, modifiers, layout, control flow inside the function
Non-composable function body	ViewModel methods, mappers, utilities, repositories
Adding a new composable	same file or new file
Reordering composables	HotSwan 1.2.0+
Resource value changes	strings.xml value, colors.xml value, dimens.xml value
Extension functions	including suspend, including vararg
Adding data class properties	API 30+ only
Numeric, string, float literal patches	compiled separately for fastest reload

Forces full rebuild (fallback)

Change	Reason
Adding or removing function parameters	method signature changes
Constructor changes	parameter list, default values, init blocks affecting fields
Interface or superclass changes	class hierarchy is part of the schema
Adding new resource ids	new R.string, R.drawable, R.id entries require generated R class regeneration
Inline functions	expanded at every call site; no discrete unit to swap
Lambda count change inside a function	internal lambda class renumbering
Removing a previously defined function	method table shrinks; schema changes
Adding data class properties below API 30	constructor schema change without ART support

Workflow when a change does not hot-reload

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.
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)?
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.
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 rare or the perf characteristic must be preserved, accept the rebuild.
5. For new resource ids, batch all id additions first, accept one rebuild, then iterate on values. Editing <string name="title">Updated Title</string> (existing id) hot-reloads; adding <string name="brand_new_id">...</string> does not.

Patterns

Pattern: function-body change (fast path) vs signature change (rebuild)

// RIGHT (body-only change, hot-reloads)
@Composable
fun Greeting() {
    Text("Hello, World", color = Color.Blue)
}

// WRONG for the fast path (signature change, forces rebuild)
@Composable
fun Greeting(name: String) {
    Text("Hello, $name")
}
// WRONG because: adding a parameter changes the method signature, which violates ART's class
// schema constraint. To stay inside the fast path, introduce the parameter with a default value
// in one save (still a rebuild; accept it once), then iterate on the body across subsequent saves.

Pattern: adding a new composable (fast path) vs changing a constructor (rebuild)

// RIGHT (new composable in the same file, hot-reloads on HotSwan 1.2.0+)
@Composable
fun SecondaryAction() {
    Text("New")
}

// WRONG for the fast path (constructor change)
data class User(val id: Long, val name: String, val age: Int)
// WRONG because: adding `age` extends the constructor. On API 30+ HotSwan supports adding
// data class properties; below API 30 the schema change forces a rebuild. When targeting older
// minSdk, batch property additions and accept a rebuild for each.

Pattern: inline function body change (rebuild)

// WRONG for the fast path
inline fun <T> Modifier.observer(value: T, body: (T) -> Modifier): Modifier = body(value)
// WRONG because: inline functions are expanded at every call site at compile time. There is no
// discrete unit to swap, so editing the inline body forces a full rebuild of every call site.
// Drop `inline` for the duration of iteration, or accept the rebuild.

// RIGHT for the fast path (non-inline variant during iteration)
fun <T> Modifier.observer(value: T, body: (T) -> Modifier): Modifier = body(value)

Pattern: resource value change (fast path) vs new resource id (rebuild)

<!-- RIGHT: value change on an existing id, hot-reloads -->
<string name="title">Updated Title</string>

<!-- WRONG for the fast path: new id, forces rebuild -->
<string name="brand_new_id">Hello</string>
<!-- WRONG because: adding a new string id grows the generated R class. R class regeneration
     is a schema change that ART cannot redefine in place. -->

Pattern: lambda count change (rebuild)

// RIGHT (body change inside the existing lambda, hot-reloads)
@Composable
fun Row() {
    Button(onClick = { log("tapped") }) { Text("Tap") }
}

// WRONG for the fast path (adds a second lambda, renumbers inner lambda classes)
@Composable
fun Row() {
    Button(onClick = { log("tapped") }) { Text("Tap") }
    Button(onClick = { log("second") }) { Text("Second") }
}
// WRONG because: a Kotlin function's compiled lambdas are anonymous classes named like
// Row$lambda$1, Row$lambda$2. Adding a lambda renumbers them and changes the class table,
// which is a schema change. The fix is to add the second composable as a separate top-level
// function (which is supported), then call it from Row once the structural change has rebuilt.

Mandatory rules

• MUST consult the boundary tables before suggesting a change to a composable that the developer is iterating on. Suggesting a parameter add when the developer wanted speed wastes the iteration loop.
• MUST NOT claim a change will hot-reload without checking it against the supported-changes table above.
• MUST NOT disable HotSwan to "force a clean rebuild". Use Gradle's :app:clean for a clean build; HotSwan auto-falls-back when needed and turning it off costs the next round-trip.
• MUST treat new resource ids and inline-function body changes as rebuild-forcing on every Android API level. The data-class-property exception is API 30+ only.
• PREFERRED: order an iteration session so body-only edits come first and signature, constructor, interface, or new-resource-id changes are batched at the end.
• PREFERRED: when a refactor needs a parameter add, introduce it once with a default value ( accept the rebuild), then iterate on the body across subsequent saves.

Verification

• A body-only change to a composable hot-reloads on save with the tool window status remaining WATCHING.
• Adding a parameter to a composable triggers the fallback status in the tool window.
• Adding a new <string> resource triggers the fallback; editing an existing <string> value does not.
• Editing the body of an inline function triggers the fallback; converting it to a non- inline function and editing the body hot-reloads.
• Adding a property to a data class hot-reloads on a device running API 30+; on API 29 and below it triggers the fallback.

References

• HotSwan supported-changes documentation: https://github.com/skydoves/compose-hotswan-web (under /docs/supported-changes).
• HotSwan limitations documentation: https://github.com/skydoves/compose-hotswan-web (under /docs/limitations).
• Android Runtime class redefinition (JVMTI) reference: https://source.android.com/docs/core/runtime/jvmti
• Sibling skill ../setting-up-compose-hotswan/SKILL.md for installation and the first save-to-reload verification.