npx skills add huanshankeji/kotlin-skills

Author: ShreckYe

.agents/skills/kotlin-debugging-unresolved-reference-file-clash/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: kotlin-debugging-unresolved-reference-file-clash
+description: >
+  Diagnoses and fixes Kotlin JVM "Unresolved reference" compilation errors
+  caused by file facade class name clashes. Use when you encounter "Unresolved
+  reference" or "can't resolve" errors in a Kotlin JVM or Kotlin Multiplatform
+  project where dependencies appear correct, especially after adding, moving,
+  or renaming Kotlin files with top-level declarations.
+license: Apache-2.0
+metadata:
+  author: huanshankeji
+  version: "1.0.0"
+---
+
+# Debugging "Unresolved reference" errors caused by Kotlin file facade clashes
+
+## Background: Kotlin file facades on JVM
+
+When a Kotlin file contains top-level declarations (functions, properties, or
+type aliases), the Kotlin/JVM compiler generates a **file facade** class in the
+output bytecode. The facade class is named `<FileName>Kt` (e.g., `Utils.kt`
+produces `UtilsKt.class`) and is placed in the package declared in the file.
+
+If two Kotlin files with the **same file name** and the **same package** end up
+on the same compilation classpath — even if they reside in different source
+directories, source sets, or modules — their generated file facade classes
+**clash**. Instead of a clear "duplicate class" message, the Kotlin compiler
+often reports **misleading "Unresolved reference"** errors on symbols that are
+actually defined correctly. This makes the root cause difficult to identify.
+
+## When to use
+
+Apply this debugging procedure when **all** of the following are true:
+
+1. The compiler reports `Unresolved reference: <symbol>` or similar "can't
+   resolve" errors.
+2. The referenced symbol **does** exist in the source code with correct
+   visibility and is in the expected dependency.
+3. Project dependencies and imports **look correct** — no obvious missing
+   dependency, typo, or visibility issue.
+
+These errors frequently occur after:
+
+- Adding a new Kotlin file that happens to share a name and package with an
+  existing file in another source set or module.
+- Moving or renaming files across source sets (e.g., `commonMain` →
+  `jvmMain` in Kotlin Multiplatform) without cleaning up the old location.
+- Refactoring that introduces files with common names (e.g., `Icons.kt`,
+  `Utils.kt`, `Extensions.kt`) in the same package across modules.
+
+## Diagnostic steps
+
+### Step 1: Search for duplicate file names in the same package
+
+Search the project for Kotlin source files (`.kt`) that share the **same file
+name** and have the **same `package` declaration**. Pay special attention to
+files across different source roots or source sets that are compiled together
+for the same target (e.g., `src/main/kotlin` and another source directory both
+feeding into a JVM compilation).
+
+```bash
+# Example: find all files named "Icons.kt" in the project
+find . -name "Icons.kt" -type f
+```
+
+Then compare the `package` declarations in each result. If two or more files
+share the same file name and the same package, you have found the clash.
+
+### Step 2: Verify the clash is the root cause
+
+Temporarily rename one of the clashing files (e.g., `Icons.kt` →
+`Icons2.kt`) and rebuild. If the "Unresolved reference" errors disappear, the
+file facade clash was the root cause.
+
+### Step 3: Apply a fix
+
+Choose one of the following fixes:
+
+#### Option A: Rename the file (recommended)
+
+Rename one of the clashing files to a unique name. This is the simplest and
+most reliable fix.
+
+```
+# Before (clash)
+moduleA/src/main/kotlin/com/example/Icons.kt
+moduleB/src/main/kotlin/com/example/Icons.kt
+
+# After (fixed)
+moduleA/src/main/kotlin/com/example/Icons.kt
+moduleB/src/main/kotlin/com/example/PlatformIcons.kt
+```
+
+#### Option B: Change the package
+
+Move one of the files to a different package so the fully qualified facade
+class names differ.
+
+#### Option C: Use `@file:JvmName` (advanced)
+
+If renaming the file is undesirable, annotate one of the files with
+`@file:JvmName` to give its facade class a different JVM name:
+
+```kotlin
+@file:JvmName("PlatformIcons")
+
+package com.example
+
+// top-level declarations...
+```
+
+This changes the generated class from `IconsKt.class` to
+`PlatformIcons.class`, resolving the clash. Note that this only affects the
+JVM facade name; Kotlin callers are unaffected.
+
+### Step 4: Clean and rebuild
+
+After applying the fix, perform a clean build to ensure no stale class files
+remain:
+
+```bash
+./gradlew clean build
+```
+
+## Common scenarios
+
+### Kotlin Multiplatform projects
+
+In Kotlin Multiplatform projects, `commonMain`, `jvmMain`, and other source
+sets are compiled together for JVM targets. A file `Utils.kt` with package
+`com.example` in `commonMain` and another `Utils.kt` with the same package in
+`jvmMain` will clash. A conventional solution here is to rename the
+platform-specific file with a platform suffix, e.g., `Utils.jvm.kt`.
+
+### Multi-module Gradle projects
+
+When module A depends on module B and both contain a file with the same name
+and package containing top-level declarations, the file facades collide on the
+classpath.
+
+### After adding or moving files
+
+AI coding agents and developers frequently trigger this when adding new files
+with common names (e.g., `Icons.kt`, `Extensions.kt`, `Helpers.kt`) without
+checking whether a same-named file already exists in the same package elsewhere
+in the project.
+
+## Guardrails
+
+- Do **not** assume the error is a missing dependency or import if the symbol
+  clearly exists in the source.
+- Do **not** add redundant dependencies or imports to try to fix the error
+  without first checking for file clashes.
+- Before creating a new Kotlin file with top-level declarations, search the
+  project for existing files with the same name in the same package.
+
+## References
+
+- [Kotlin documentation: Packages and imports](https://kotlinlang.org/docs/packages.html)
+- [Kotlin documentation: Java interop — Package-level functions](https://kotlinlang.org/docs/java-to-kotlin-interop.html#package-level-functions)
+- [KT-83413: Misleading "Unresolved reference" errors caused by file facade class name clashes](https://youtrack.jetbrains.com/issue/KT-83413)

skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "kotlin-debugging-unresolved-reference-file-clash": {
+      "source": "huanshankeji/kotlin-skills",
+      "sourceType": "github",
+      "computedHash": "d5173ec93bdf44b3eda8c4ccf1f4e59ce9eb8fad43187dc781bdd8050d62db8e"
+    }
+  }
+}