From c8fa8e804eb72512aee01d6e93549e448390fcdd Mon Sep 17 00:00:00 2001
From: hatayama <booqle@gmail.com>
Date: Fri, 24 Jul 2026 15:48:06 +0900
Subject: [PATCH 1/2] Document that --force-recompile is rarely needed in
 compile skill

Unity already detects and recompiles changed files on a plain
`uloop compile`, even when files were edited outside the Editor.
Add a "When to use --force-recompile" section explaining why the
flag should be avoided (freezes large projects, crosses Domain
Reload leaving Success as null, destabilizes the Editor) and the
one legitimate exception, mirroring the guidance already present
on the v3-beta branch.
---
 .agents/skills/uloop-compile/SKILL.md         | 20 ++++++++++++++++++-
 .claude/skills/uloop-compile/SKILL.md         | 20 ++++++++++++++++++-
 .../Api/McpTools/Compile/Skill/SKILL.md       | 20 ++++++++++++++++++-
 3 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/.agents/skills/uloop-compile/SKILL.md b/.agents/skills/uloop-compile/SKILL.md
index 0f6846d80d..a4af547e8d 100644
--- a/.agents/skills/uloop-compile/SKILL.md
+++ b/.agents/skills/uloop-compile/SKILL.md
@@ -17,9 +17,27 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Pass `true` or `false`; bare flags are not accepted. |
+| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Rarely needed — see "When to use --force-recompile" below. Pass `true` or `false`; bare flags are not accepted. |
 | `--wait-for-domain-reload` | boolean value | `false` | Wait until Domain Reload completes before returning. Pass `true` or `false`; bare flags are not accepted. |
 
+## When to use --force-recompile
+
+`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
+files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
+recompilation the changes require. "The files were changed externally, so recompile everything
+just in case" is not a valid reason.
+
+Why to avoid it:
+
+- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
+- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
+  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
+  not work as a verification step.
+- It puts the Editor into the unstable just-after-reload state for no benefit.
+
+The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
+build. Otherwise always run plain `uloop compile`.
+
 ## Global Options
 
 | Option | Description |
diff --git a/.claude/skills/uloop-compile/SKILL.md b/.claude/skills/uloop-compile/SKILL.md
index 0f6846d80d..a4af547e8d 100644
--- a/.claude/skills/uloop-compile/SKILL.md
+++ b/.claude/skills/uloop-compile/SKILL.md
@@ -17,9 +17,27 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Pass `true` or `false`; bare flags are not accepted. |
+| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Rarely needed — see "When to use --force-recompile" below. Pass `true` or `false`; bare flags are not accepted. |
 | `--wait-for-domain-reload` | boolean value | `false` | Wait until Domain Reload completes before returning. Pass `true` or `false`; bare flags are not accepted. |
 
+## When to use --force-recompile
+
+`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
+files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
+recompilation the changes require. "The files were changed externally, so recompile everything
+just in case" is not a valid reason.
+
+Why to avoid it:
+
+- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
+- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
+  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
+  not work as a verification step.
+- It puts the Editor into the unstable just-after-reload state for no benefit.
+
+The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
+build. Otherwise always run plain `uloop compile`.
+
 ## Global Options
 
 | Option | Description |
diff --git a/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md b/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
index 0f6846d80d..a4af547e8d 100644
--- a/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
+++ b/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
@@ -17,9 +17,27 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Pass `true` or `false`; bare flags are not accepted. |
+| `--force-recompile` | boolean value | `false` | Force full recompilation (triggers Domain Reload). Rarely needed — see "When to use --force-recompile" below. Pass `true` or `false`; bare flags are not accepted. |
 | `--wait-for-domain-reload` | boolean value | `false` | Wait until Domain Reload completes before returning. Pass `true` or `false`; bare flags are not accepted. |
 
+## When to use --force-recompile
+
+`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
+files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
+recompilation the changes require. "The files were changed externally, so recompile everything
+just in case" is not a valid reason.
+
+Why to avoid it:
+
+- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
+- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
+  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
+  not work as a verification step.
+- It puts the Editor into the unstable just-after-reload state for no benefit.
+
+The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
+build. Otherwise always run plain `uloop compile`.
+
 ## Global Options
 
 | Option | Description |

From cdd294f6f4d7e6bbe05100e465eb2e845104403b Mon Sep 17 00:00:00 2001
From: hatayama <booqle@gmail.com>
Date: Fri, 24 Jul 2026 15:59:18 +0900
Subject: [PATCH 2/2] Condense the --force-recompile guidance into a single
 paragraph

The section repeated the same point in three forms and listed a weak
"unstable just-after-reload state" bullet that overlaps with the freeze
concern. Keep only the load-bearing facts: Unity detects external edits
by itself, a forced recompile can freeze large projects and makes
Success come back as null with --wait-for-domain-reload, and the only
legitimate use is surfacing warnings hidden by other asmdefs.
---
 .agents/skills/uloop-compile/SKILL.md         | 21 ++++++-------------
 .claude/skills/uloop-compile/SKILL.md         | 21 ++++++-------------
 .../Api/McpTools/Compile/Skill/SKILL.md       | 21 ++++++-------------
 3 files changed, 18 insertions(+), 45 deletions(-)

diff --git a/.agents/skills/uloop-compile/SKILL.md b/.agents/skills/uloop-compile/SKILL.md
index a4af547e8d..26313a5318 100644
--- a/.agents/skills/uloop-compile/SKILL.md
+++ b/.agents/skills/uloop-compile/SKILL.md
@@ -22,21 +22,12 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 ## When to use --force-recompile
 
-`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
-files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
-recompilation the changes require. "The files were changed externally, so recompile everything
-just in case" is not a valid reason.
-
-Why to avoid it:
-
-- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
-- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
-  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
-  not work as a verification step.
-- It puts the Editor into the unstable just-after-reload state for no benefit.
-
-The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
-build. Otherwise always run plain `uloop compile`.
+Almost never. Unity itself detects changed files — even when they were edited outside the
+Editor, a plain `uloop compile` runs every recompilation the changes require. A forced full
+recompile can freeze the Editor for a long time on large projects, and with
+`--wait-for-domain-reload true` the response crosses a Domain Reload so `Success` comes back
+as `null`, making it useless as a verification step. The only legitimate use: surfacing
+warnings hidden by other asmdefs with a full build.
 
 ## Global Options
 
diff --git a/.claude/skills/uloop-compile/SKILL.md b/.claude/skills/uloop-compile/SKILL.md
index a4af547e8d..26313a5318 100644
--- a/.claude/skills/uloop-compile/SKILL.md
+++ b/.claude/skills/uloop-compile/SKILL.md
@@ -22,21 +22,12 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 ## When to use --force-recompile
 
-`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
-files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
-recompilation the changes require. "The files were changed externally, so recompile everything
-just in case" is not a valid reason.
-
-Why to avoid it:
-
-- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
-- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
-  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
-  not work as a verification step.
-- It puts the Editor into the unstable just-after-reload state for no benefit.
-
-The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
-build. Otherwise always run plain `uloop compile`.
+Almost never. Unity itself detects changed files — even when they were edited outside the
+Editor, a plain `uloop compile` runs every recompilation the changes require. A forced full
+recompile can freeze the Editor for a long time on large projects, and with
+`--wait-for-domain-reload true` the response crosses a Domain Reload so `Success` comes back
+as `null`, making it useless as a verification step. The only legitimate use: surfacing
+warnings hidden by other asmdefs with a full build.
 
 ## Global Options
 
diff --git a/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md b/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
index a4af547e8d..26313a5318 100644
--- a/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
+++ b/Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md
@@ -22,21 +22,12 @@ uloop compile [--force-recompile <true|false>] [--wait-for-domain-reload <true|f
 
 ## When to use --force-recompile
 
-`--force-recompile true` is almost never needed. Detecting changed files is Unity's job: even when
-files were edited outside the Editor, a plain `uloop compile` refreshes assets and runs every
-recompilation the changes require. "The files were changed externally, so recompile everything
-just in case" is not a valid reason.
-
-Why to avoid it:
-
-- On large projects a full recompile plus Domain Reload can freeze Unity for a long time.
-- With `--wait-for-domain-reload true`, the response crosses a Domain Reload and Unity cannot
-  summarize compiler messages until after reload, so `Success` comes back as `null` and it does
-  not work as a verification step.
-- It puts the Editor into the unstable just-after-reload state for no benefit.
-
-The one legitimate use case: you need warnings hidden by other asmdefs surfaced by a full
-build. Otherwise always run plain `uloop compile`.
+Almost never. Unity itself detects changed files — even when they were edited outside the
+Editor, a plain `uloop compile` runs every recompilation the changes require. A forced full
+recompile can freeze the Editor for a long time on large projects, and with
+`--wait-for-domain-reload true` the response crosses a Domain Reload so `Success` comes back
+as `null`, making it useless as a verification step. The only legitimate use: surfacing
+warnings hidden by other asmdefs with a full build.
 
 ## Global Options