fix: Document that --force-recompile is rarely needed in compile skill

[hatayama]

Summary

• Add a "When to use --force-recompile" section to the uloop-compile skill, explaining that the flag is almost never needed since Unity already detects and recompiles changed files on a plain uloop compile
• Document why it should be avoided: it can freeze large projects, crosses a Domain Reload so Success comes back as null (unusable for verification), and leaves the Editor in an unstable post-reload state
• Mirrors the guidance already present in the v3-beta branch's compile skill

Test plan

• Verified the source SKILL.md and its two generated copies (.claude/skills, .agents/skills) are byte-identical

Summary

• Documented when uloop-compile --force-recompile true should and should not be used, emphasizing it’s rarely needed because Unity auto-detects changes (including externally edited files) during a standard uloop compile.
• Clarified that --force-recompile and --wait-for-domain-reload require explicit true/false values and do not accept bare flags.
• Added cautions that forced recompilation can freeze large Unity projects, and that combining --wait-for-domain-reload true can cause the skill to return Success: null, making the result unusable for verification.
• Documented the only legitimate use case: surfacing warnings hidden by other assembly definitions.
• Synchronized the guidance across all copies of the skill documentation (including the v3-beta-mirrored content), verified as byte-identical between source and generated skill docs.

[coderabbitai]

📝 Walkthrough

Walkthrough

The compile skill documentation is synchronized across three locations. Parameter descriptions now require explicit boolean values, and new guidance explains --force-recompile, Domain Reload behavior, editor-freeze risks, and Success returning null after waiting.

Changes

Compile documentation

Layer / File(s)	Summary
Compile option parameter guidance .agents/skills/uloop-compile/SKILL.md, .claude/skills/uloop-compile/SKILL.md, Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md	Parameter descriptions require explicit true/false values, reject bare flags, and describe Domain Reload behavior.
Force-recompile usage guidance .agents/skills/uloop-compile/SKILL.md, .claude/skills/uloop-compile/SKILL.md, Packages/src/Editor/Api/McpTools/Compile/Skill/SKILL.md	A new section documents the rare valid use case, editor-freeze risk, compiler-message handling, and Success returning null after waiting for Domain Reload.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• hatayama/unity-cli-loop#1031: Updates the same compile option documentation.
• hatayama/unity-cli-loop#1206: Overlaps on --force-recompile and Domain Reload guidance.
• hatayama/unity-cli-loop#1836: Updates the same parameter and usage documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: documenting that --force-recompile is rarely needed in the compile skill.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/compile-skill-force-recompile-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}