Understanding Hot Reload Limits

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 87cfb886f00d · 16 Oct 2026Report an issue or request a re-scan

• Publisherskydoves GitHub userOwner of the repository this skill is read from
• Source folderskydoves/compose-performance-skills/hot-reload/understanding-hot-reload-limitsThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict87cfb886f00dA new audit runs when the source changes
• Repository statusNot archivedLast push 121 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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)

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

```kotlin
// 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 c

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/skydoves/compose-performance-skills
git -C compose-performance-skills checkout 87cfb886f00d

Works in

1. 2026-10-16
   ✓SAFE B 89 / 100

   first audit · source 87cfb886f00d

Questions about Understanding Hot Reload Limits

• github.com/skydoves/compose-performance-skills/tree/main/hot-rel — the audited source at commit 87cfb886f00d and every finding aboveObserved · 16 Oct 2026

Spotted something wrong? Report a correction · Methodology