UnityLaparoscopicSceneSimulator/.opencode/skills/unity-hierarchy-hygiene/SKILL.md

name, description

name	description
unity-hierarchy-hygiene	Maintain a clean, readable, reusable Unity scene hierarchy in the LaparoscopicSurgeryEmulation scene. Use when adding, moving, renaming, parenting, prefab-ifying, or activating GameObjects under the SurgeryBenchmark/ authored roots.

Unity Hierarchy Hygiene (project-scoped)

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

When to load

Load when the agent is about to:

• Create, rename, move, parent, or delete any GameObject in the active scene.
• Convert a GameObject to a prefab, or instantiate a prefab into a slot.
• Activate or deactivate a scenario root.
• Touch the SurgeryBenchmark/* authored roots or the SurgeryBenchmark/Shared/*Slot replacement anchors.

The authoring contract (from Assets/Scenes/LaparoscopicSurgeryEmulation.md)

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 placeholder, instrument placeholder)	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 subagents) toggles scenario roots only. Never rename, never reorder, never reparent scenario roots or slot anchors.

Off-limits subtrees (preserved from MainScene)

Do not rename, move, delete, or restructure objects that came from MainScene:

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

These are the project's external-interop surface. Renaming them breaks WebRTC peers and any automation that addresses them by name.

Naming convention

Use PascalCase for GameObject names that act as authored containers (AnatomySlot, CavitySlot). Use descriptive PascalCase for everything else (CavityWall_Main, Tissue_Default_Slot01). Avoid spaces, avoid leading numbers, avoid names that look like IDs (e.g., Cube_42 is acceptable as a primitive placeholder but should be renamed before promotion).

For dynamically generated objects (e.g., benchmark instances), use the pattern <Type>_<ScenarioTag>_<Index>:

• CavityWall_S02_00
• Tissue_Default_S01_00
• InstrumentProxy_S05_00

Parenting rules

1. Slot rule. Anything that fills AnatomySlot, CavitySlot, or InstrumentSlot lives as a child of the slot, not as a sibling. This keeps the slot a stable, swappable anchor.
2. Scenario rule. Scenario-specific geometry goes under the scenario root. Anything shared across scenarios goes under SurgeryBenchmark/Shared.
3. Scaffolding rule. Editor scaffolding (gizmos, debug helpers, placeholders) goes under SurgeryBenchmark/Shared/_Editor (prefix with underscore) so it is obvious it is not authored content. Off by default in builds if you control build settings; otherwise hide via the _Editor convention.
4. No flat hierarchies. If you are about to add a top-level GameObject, stop — almost everything should be under SurgeryBenchmark/... or under one of the preserved MainScene subtrees.

Prefab boundaries

• A GameObject becomes a prefab when more than one scenario needs the same instance, or when the agent wants the change to be reusable across scenes.
• Prefabs for this project live in Assets/Prefabs/LaparoscopicBenchmark/ (create the folder if missing; this is bounded).
• Slot contents that are reusable across scenarios should be authored as a prefab variant rooted at the slot, not as a duplicated hierarchy.
• When converting to a prefab, use manage_prefabs(action="create_from_gameobject") and prefab_folder="Assets/Prefabs/LaparoscopicBenchmark". Reuse the existing one if it already exists.

Activation vs destruction

Default to activation (SetActive(false) on a scenario root) over deletion. The five scenario roots are an explicit external contract — they exist so external automation can toggle them. Deleting one breaks the contract.

If a child object truly has no future use, prefer to move it under SurgeryBenchmark/Shared/_Retired (with a one-line note in the handoff) rather than delete it. Destructive deletions of authored content require explicit approval.

Common operations and the right MCP call

Intent	MCP call	Notes
Activate a scenario	manage_gameobject(action="modify", target="Scenario_02_WetSpecular", search_method="by_path", set_active=true)	Always by path, not by name, to avoid collisions
Deactivate siblings	Same with set_active=false	Do it as a batch
Add a child to a slot	manage_gameobject(action="create", name="...", parent="AnatomySlot", search_method="by_path", primitive_type=...)	Parent path is stable
Rename	manage_gameobject(action="modify", target="...", new_name="...")	Only inside the authored roots, never on the scenario roots or slots
Inspect children	find_gameobjects(search_term="SurgeryBenchmark/Shared", search_method="by_path", include_inactive=true)	Use to confirm activation state before activating
Convert to prefab	manage_prefabs(action="create_from_gameobject", target="...", prefab_path="Assets/Prefabs/LaparoscopicBenchmark/<Name>.prefab")	Then re-instantiate in each scenario via manage_gameobject or by editing the scenario root

Reversibility checklist (before any hierarchy change)

1. Is the target under SurgeryBenchmark/... or a preserved MainScene subtree? If preserved, stop and ask.
2. Will renaming it break any script reference, prefab variant, or external automation? If yes, stop and ask.
3. Can the change be expressed as "toggle active" instead of "delete"? If yes, prefer that.
4. Is the new name in PascalCase and descriptive? If not, fix it.
5. After the change, does read_console show missing-reference warnings? If yes, fix before reporting done.

Anti-patterns to refuse

• Adding top-level GameObjects outside SurgeryBenchmark/... and the preserved subtrees.
• Renaming SurgeryBenchmark/Scenarios/Scenario_0X_* roots or SurgeryBenchmark/Shared/*Slot anchors.
• Moving the stereo rig, Blending, UI, WebRTC, or RPC objects.
• Deleting a scenario root instead of deactivating it.
• Flat hierarchies with 10+ top-level GameObjects that should be in a container.
• Magic-number indices (Cube (42)) being promoted to authored names.
• Creating prefabs in the root of Assets/ instead of Assets/Prefabs/LaparoscopicBenchmark/.