UnityLaparoscopicSceneSimulator/.claude/commands/unity-hierarchy-hygiene.md

Unity Hierarchy Hygiene (project-scoped)

Encodes the scene's authoring contract so additions stay reversible, organized, and do not collide with the preserved MainScene objects.

When to use

Load before creating, moving, renaming, parenting, prefab-ifying, or activating any GameObject in the active scene.

The authoring contract

These paths are the stable contract for external control. Do not rename or move them.

Path	Role	Default state
SurgeryBenchmark/Shared	Reusable assets (cavity, anatomy, instrument)	active
SurgeryBenchmark/Shared/AnatomySlot	Replacement anchor for the organ mesh	empty / placeholder
SurgeryBenchmark/Shared/CavitySlot	Replacement anchor for the cavity wall	empty / placeholder
SurgeryBenchmark/Shared/InstrumentSlot	Replacement anchor for the instrument proxy	empty / placeholder
SurgeryBenchmark/Scenarios/Scenario_01_CleanTissue	Active benchmark scenario	active
SurgeryBenchmark/Scenarios/Scenario_02_WetSpecular	Wet specular variant	inactive
SurgeryBenchmark/Scenarios/Scenario_03_LowTexture	Low-texture variant	inactive
SurgeryBenchmark/Scenarios/Scenario_04_PartialOcclusion	Partial occlusion variant	inactive
SurgeryBenchmark/Scenarios/Scenario_05_InstrumentOcclusion	Instrument occlusion variant	inactive

External automation (including agents) toggles scenario roots only. Never rename, never reorder, never reparent them.

Off-limits subtrees (preserved from MainScene)

Do not rename, move, delete, or restructure:

• The stereo rig (left + right laparoscope cameras and their parents).
• Blending (depth / colour blend controller).
• UI canvases and UI events.
• WebRTC sender / receiver objects (driven by WEBRTCSender.cs).
• RPC objects (driven by CrpcApi.cs / MinimalRpcServer.cs).

Naming convention

• PascalCase for authored containers (AnatomySlot, CavitySlot).
• Descriptive PascalCase for everything else (CavityWall_Main, Tissue_Default_Slot01).
• No spaces, no leading numbers.
• Dynamically generated objects: <Type>_<ScenarioTag>_<Index> (e.g., CavityWall_S02_00, Tissue_Default_S01_00).
• Editor scaffolding: prefix with underscore (_Editor, _Cameras, _Retired) — obviously not authored content.

Parenting rules

1. Slot rule. Anything filling AnatomySlot, CavitySlot, or InstrumentSlot lives as a child of the slot.
2. Scenario rule. Scenario-specific geometry goes under the scenario root. Shared content goes under SurgeryBenchmark/Shared.
3. Scaffolding rule. Editor helpers go under SurgeryBenchmark/Shared/_Editor.

Prefab rules

• Prefab source goes in Assets/Prefabs/LaparoscopicBenchmark/.
• Convert with mcp__UnityMCP__manage_prefabs(action="create_from_gameobject", ...).
• Do not overwrite existing prefabs without a bounded change statement.

Activation rules

• Only toggle SetActive on the five Scenario_0X_* roots.
• Slot anchors are always active (they are containers, not content).
• Do not deactivate the preserved MainScene subtrees.

Common MCP calls

Intent	Call
Find authored roots	mcp__UnityMCP__find_gameobjects(search_term="SurgeryBenchmark", search_method="by_path", include_inactive=true)
Activate a scenario	mcp__UnityMCP__manage_gameobject(action="modify", target="SurgeryBenchmark/Scenarios/Scenario_02_WetSpecular", search_method="by_path", set_active=true)
Create child under slot	mcp__UnityMCP__manage_gameobject(action="create", name="CavityWall_Main", parent="SurgeryBenchmark/Shared/CavitySlot", search_method="by_path", primitive_type="Sphere")
Create a prefab	mcp__UnityMCP__manage_prefabs(action="create_from_gameobject", target="...", prefab_path="Assets/Prefabs/LaparoscopicBenchmark/<Name>.prefab")