feat: Debug.Break pauses can now be inspected with uloop

.agents/skills/uloop-control-play-mode/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: uloop-control-play-mode
 toolName: control-play-mode
-description: "Control Unity Editor Play Mode. Use to start, stop, or pause Play Mode for runtime behavior checks and frame inspection."
+description: "Control Unity Editor Play Mode. Use to start, stop, pause, or advance one paused PlayMode frame for runtime behavior checks and frame inspection."
 ---
 
 # uloop control-play-mode
 
-Control Unity Editor play mode (play/stop/pause).
+Control Unity Editor play mode (play/stop/pause/next frame).
 
 ## Usage
 
@@ -18,7 +18,7 @@ uloop control-play-mode [options]
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--action` | string | `Play` | Action to perform: `Play`, `Stop`, `Pause` |
+| `--action` | string | `Play` | Action to perform: `Play`, `Stop`, `Pause`, `NextFrame` |
 | `--timeout-seconds` | integer | `180` | Maximum seconds to wait for the requested play mode state |
 
 ## Global Options
@@ -41,6 +41,9 @@ uloop control-play-mode --action Stop
 
 # Pause play mode
 uloop control-play-mode --action Pause
+
+# Advance one frame while paused in play mode
+uloop control-play-mode --action NextFrame
 ```
 
 ## Output
@@ -55,5 +58,6 @@ Returns JSON with the current play mode state:
 - Play action starts the game in the Unity Editor (also resumes from pause)
 - Stop action exits play mode and returns to edit mode
 - Pause action pauses the game while remaining in play mode
+- NextFrame action advances one frame only when Unity is already paused in PlayMode; otherwise it is ignored
 - Useful for automated testing workflows
-- The command waits for the requested state before returning. Increase `--timeout-seconds` for projects with slow PlayMode entry.
+- Play, Stop, and Pause wait for the requested state before returning. Increase `--timeout-seconds` for projects with slow PlayMode entry.

.agents/skills/uloop-execute-dynamic-code/SKILL.md

@@ -83,4 +83,4 @@ For detailed code examples, refer to these files:
 - **PlayMode UI controls**: See [references/playmode-ui-controls.md](references/playmode-ui-controls.md)
   - InputField, Slider, Toggle, Dropdown, drag & drop simulation, list all UI controls
 - **PlayMode inspection**: See [references/playmode-inspection.md](references/playmode-inspection.md)
-  - Scene info, game state via reflection, physics state, raycast checks, GameObject search, position/rotation
+  - Scene info, game state via reflection, physics state, raycast checks, GameObject search, position/rotation, scheduled Debug.Break inspection

.agents/skills/uloop-execute-dynamic-code/references/playmode-inspection.md

@@ -117,6 +117,39 @@ Transform t = target.transform;
 return $"{target.name}: pos={t.position}, rot={t.rotation.eulerAngles}, scale={t.localScale}";
 ```
 
+## Schedule Debug.Break for Later Inspection
+
+Use this pattern when direct inspection is not enough and you want Unity to pause after a short delay or after the next runtime updates. Start `uloop wait-for-debug-break` in another session before triggering this snippet, or give the delay enough time to start the wait immediately after scheduling it. If Unity pauses before the wait command starts, the wait command will reject the stale pause.
+
+```csharp
+using UnityEditor;
+using UnityEngine;
+
+double startedAt = EditorApplication.timeSinceStartup;
+double delaySeconds = 3d;
+
+EditorApplication.CallbackFunction tick = null;
+tick = () =>
+{
+    if (EditorApplication.timeSinceStartup - startedAt < delaySeconds)
+    {
+        return;
+    }
+
+    EditorApplication.update -= tick;
+
+    GameObject player = GameObject.Find("Player");
+    Vector3 position = player != null ? player.transform.position : Vector3.zero;
+    Debug.Log($"[DebugBreak] delayed break after {delaySeconds}s, playerExists={player != null}, playerPosition={position}");
+    Debug.Break();
+};
+
+EditorApplication.update += tick;
+return $"Scheduled Debug.Break in {delaySeconds} seconds.";
+```
+
+After the wait command observes the pause, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another `uloop execute-dynamic-code` call. Resume PlayMode with `uloop control-play-mode --action Play` when inspection is complete.
+
 ## Check Rigidbody State
 
 ```csharp

.agents/skills/uloop-simulate-keyboard/SKILL.md

@@ -14,7 +14,18 @@ Simulate keyboard input on Unity PlayMode: $ARGUMENTS
 1. Ensure Unity is in PlayMode (use `uloop control-play-mode --action Play` if not)
 2. Execute the appropriate `uloop simulate-keyboard` command
 3. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-4. Report what happened
+4. If a screenshot cannot prove the gameplay state changed, use the Debug.Break verification workflow below
+5. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when input appears to fire but the result is hard to verify visually, such as pressing Space to jump and needing to confirm the player actually entered the jump state.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as position, velocity, grounded flags, or animation state.
+3. Trigger the keyboard input before the delay expires, for example `uloop simulate-keyboard --action Press --key Space`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference
 

.agents/skills/uloop-simulate-mouse-input/SKILL.md

@@ -15,7 +15,18 @@ Simulate mouse input via Input System in Unity PlayMode: $ARGUMENTS
 2. For Click/LongPress: determine the target screen position (use `uloop screenshot` to find coordinates)
 3. Execute the appropriate `uloop simulate-mouse-input` command
 4. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-5. Report what happened
+5. If a screenshot cannot prove the gameplay state changed, use the Debug.Break verification workflow below
+6. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when mouse input appears to fire but the resulting gameplay state is hard to confirm visually, such as a click that should place or destroy an object, a mouse delta that should rotate a camera, or a scroll action that should change a selected slot.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as target object existence, camera rotation, selected slot, hit result, or component fields.
+3. Trigger the mouse input before the delay expires, for example `uloop simulate-mouse-input --action Click --x 400 --y 300 --button Right`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference
 

.agents/skills/uloop-simulate-mouse-ui/SKILL.md

@@ -16,7 +16,18 @@ Simulate mouse interaction on Unity PlayMode UI: $ARGUMENTS
 3. Use the `AnnotatedElements` array to find the target element by `Label`, `Name`, or `Path` (A=frontmost, B=next, ...). Use `Interaction` to distinguish click targets from drag/drop/text targets, then use `SimX`/`SimY` directly as `--x`/`--y` coordinates.
 4. Execute the appropriate `uloop simulate-mouse-ui` command
 5. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering --annotate-elements`
-6. Report what happened
+6. If a screenshot cannot prove the UI state changed, use the Debug.Break verification workflow below
+7. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when UI pointer events appear to fire but the resulting state is hard to confirm visually, such as a button callback that should update game state, a long-press that should open a menu, or a drag/drop action that should mutate inventory data.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as selected item, active panel, inventory contents, button callback side effects, or component fields.
+3. Trigger the UI mouse action before the delay expires, for example `uloop simulate-mouse-ui --action Click --x 400 --y 300`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference
 

.agents/skills/uloop-wait-for-debug-break/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: uloop-wait-for-debug-break
+description: "Wait until Unity Editor pauses after Debug.Break. Use when log output is too noisy to inspect live, or when input simulation needs a precise pause point for state inspection."
+---
+
+# uloop wait-for-debug-break
+
+Wait until Unity Editor becomes paused after a `Debug.Break()` call.
+
+## Usage
+
+```bash
+uloop wait-for-debug-break
+```
+
+## Parameters
+
+None.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--project-path <path>` | Optional. Use only when the target Unity project is not the current directory. |
+
+## Workflow
+
+1. Add a temporary marker before the break point:
+
+```csharp
+UnityEngine.Debug.Log("[DebugBreak] reached target state");
+UnityEngine.Debug.Break();
+```
+
+2. Start the wait command before triggering the behavior:
+
+```bash
+uloop wait-for-debug-break
+```
+
+3. Trigger the action, input simulation, or reproduction path.
+4. When the command returns success, inspect Unity Console, Hierarchy, Inspector, or other uLoop state commands while Unity is paused.
+5. Resume Unity after inspection:
+
+```bash
+uloop control-play-mode --action Play
+```
+
+6. Remove the temporary `Debug.Break()` and marker log unless the break is intentionally part of the debugging workflow.
+
+## Output
+
+Returns JSON with:
+
+- `Success`: Whether the pause was observed
+- `IsPlaying`: Current Unity PlayMode state
+- `IsPaused`: Current Unity paused state
+- `ElapsedMilliseconds`: Time spent waiting
+- `Message`: Status message
+
+## Notes
+
+- Start this command while Unity is not paused. If Unity is already paused, the command fails to avoid confusing an old pause with the target `Debug.Break()`.
+- This command polls a lightweight internal PlayMode-state bridge and can be left waiting while other uLoop commands are used.
+- This command only observes Unity pause state. If it was started accidentally, stop the CLI process from the runner/session that started it.
+- Resume a Debug.Break pause with `uloop control-play-mode --action Play`; existing control-play-mode behavior clears `EditorApplication.isPaused`.
+- Remove the temporary `Debug.Break()` call from code to prevent future pauses.
+- Use marker logs when several code paths can pause Unity, then inspect the Console after the wait completes.

.claude/skills/uloop-control-play-mode/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: uloop-control-play-mode
 toolName: control-play-mode
-description: "Control Unity Editor Play Mode. Use to start, stop, or pause Play Mode for runtime behavior checks and frame inspection."
+description: "Control Unity Editor Play Mode. Use to start, stop, pause, or advance one paused PlayMode frame for runtime behavior checks and frame inspection."
 ---
 
 # uloop control-play-mode
 
-Control Unity Editor play mode (play/stop/pause).
+Control Unity Editor play mode (play/stop/pause/next frame).
 
 ## Usage
 
@@ -18,7 +18,7 @@ uloop control-play-mode [options]
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `--action` | string | `Play` | Action to perform: `Play`, `Stop`, `Pause` |
+| `--action` | string | `Play` | Action to perform: `Play`, `Stop`, `Pause`, `NextFrame` |
 | `--timeout-seconds` | integer | `180` | Maximum seconds to wait for the requested play mode state |
 
 ## Global Options
@@ -41,6 +41,9 @@ uloop control-play-mode --action Stop
 
 # Pause play mode
 uloop control-play-mode --action Pause
+
+# Advance one frame while paused in play mode
+uloop control-play-mode --action NextFrame
 ```
 
 ## Output
@@ -55,5 +58,6 @@ Returns JSON with the current play mode state:
 - Play action starts the game in the Unity Editor (also resumes from pause)
 - Stop action exits play mode and returns to edit mode
 - Pause action pauses the game while remaining in play mode
+- NextFrame action advances one frame only when Unity is already paused in PlayMode; otherwise it is ignored
 - Useful for automated testing workflows
-- The command waits for the requested state before returning. Increase `--timeout-seconds` for projects with slow PlayMode entry.
+- Play, Stop, and Pause wait for the requested state before returning. Increase `--timeout-seconds` for projects with slow PlayMode entry.

.claude/skills/uloop-execute-dynamic-code/SKILL.md

@@ -83,4 +83,4 @@ For detailed code examples, refer to these files:
 - **PlayMode UI controls**: See [references/playmode-ui-controls.md](references/playmode-ui-controls.md)
   - InputField, Slider, Toggle, Dropdown, drag & drop simulation, list all UI controls
 - **PlayMode inspection**: See [references/playmode-inspection.md](references/playmode-inspection.md)
-  - Scene info, game state via reflection, physics state, raycast checks, GameObject search, position/rotation
+  - Scene info, game state via reflection, physics state, raycast checks, GameObject search, position/rotation, scheduled Debug.Break inspection

.claude/skills/uloop-execute-dynamic-code/references/playmode-inspection.md

@@ -117,6 +117,39 @@ Transform t = target.transform;
 return $"{target.name}: pos={t.position}, rot={t.rotation.eulerAngles}, scale={t.localScale}";
 ```
 
+## Schedule Debug.Break for Later Inspection
+
+Use this pattern when direct inspection is not enough and you want Unity to pause after a short delay or after the next runtime updates. Start `uloop wait-for-debug-break` in another session before triggering this snippet, or give the delay enough time to start the wait immediately after scheduling it. If Unity pauses before the wait command starts, the wait command will reject the stale pause.
+
+```csharp
+using UnityEditor;
+using UnityEngine;
+
+double startedAt = EditorApplication.timeSinceStartup;
+double delaySeconds = 3d;
+
+EditorApplication.CallbackFunction tick = null;
+tick = () =>
+{
+    if (EditorApplication.timeSinceStartup - startedAt < delaySeconds)
+    {
+        return;
+    }
+
+    EditorApplication.update -= tick;
+
+    GameObject player = GameObject.Find("Player");
+    Vector3 position = player != null ? player.transform.position : Vector3.zero;
+    Debug.Log($"[DebugBreak] delayed break after {delaySeconds}s, playerExists={player != null}, playerPosition={position}");
+    Debug.Break();
+};
+
+EditorApplication.update += tick;
+return $"Scheduled Debug.Break in {delaySeconds} seconds.";
+```
+
+After the wait command observes the pause, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another `uloop execute-dynamic-code` call. Resume PlayMode with `uloop control-play-mode --action Play` when inspection is complete.
+
 ## Check Rigidbody State
 
 ```csharp

.claude/skills/uloop-simulate-keyboard/SKILL.md

@@ -14,7 +14,18 @@ Simulate keyboard input on Unity PlayMode: $ARGUMENTS
 1. Ensure Unity is in PlayMode (use `uloop control-play-mode --action Play` if not)
 2. Execute the appropriate `uloop simulate-keyboard` command
 3. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-4. Report what happened
+4. If a screenshot cannot prove the gameplay state changed, use the Debug.Break verification workflow below
+5. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when input appears to fire but the result is hard to verify visually, such as pressing Space to jump and needing to confirm the player actually entered the jump state.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as position, velocity, grounded flags, or animation state.
+3. Trigger the keyboard input before the delay expires, for example `uloop simulate-keyboard --action Press --key Space`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference
 

.claude/skills/uloop-simulate-mouse-input/SKILL.md

@@ -15,7 +15,18 @@ Simulate mouse input via Input System in Unity PlayMode: $ARGUMENTS
 2. For Click/LongPress: determine the target screen position (use `uloop screenshot` to find coordinates)
 3. Execute the appropriate `uloop simulate-mouse-input` command
 4. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering`
-5. Report what happened
+5. If a screenshot cannot prove the gameplay state changed, use the Debug.Break verification workflow below
+6. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when mouse input appears to fire but the resulting gameplay state is hard to confirm visually, such as a click that should place or destroy an object, a mouse delta that should rotate a camera, or a scroll action that should change a selected slot.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as target object existence, camera rotation, selected slot, hit result, or component fields.
+3. Trigger the mouse input before the delay expires, for example `uloop simulate-mouse-input --action Click --x 400 --y 300 --button Right`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference
 

.claude/skills/uloop-simulate-mouse-ui/SKILL.md

@@ -16,7 +16,18 @@ Simulate mouse interaction on Unity PlayMode UI: $ARGUMENTS
 3. Use the `AnnotatedElements` array to find the target element by `Label`, `Name`, or `Path` (A=frontmost, B=next, ...). Use `Interaction` to distinguish click targets from drag/drop/text targets, then use `SimX`/`SimY` directly as `--x`/`--y` coordinates.
 4. Execute the appropriate `uloop simulate-mouse-ui` command
 5. Take a screenshot to verify the result: `uloop screenshot --capture-mode rendering --annotate-elements`
-6. Report what happened
+6. If a screenshot cannot prove the UI state changed, use the Debug.Break verification workflow below
+7. Report what happened
+
+## Debug.Break Verification Workflow
+
+Use this when UI pointer events appear to fire but the resulting state is hard to confirm visually, such as a button callback that should update game state, a long-press that should open a menu, or a drag/drop action that should mutate inventory data.
+
+1. Start `uloop wait-for-debug-break` in another terminal/session.
+2. Add a temporary delayed `Debug.Break()` marker in the project code path under test, and log the state you need to inspect, such as selected item, active panel, inventory contents, button callback side effects, or component fields.
+3. Trigger the UI mouse action before the delay expires, for example `uloop simulate-mouse-ui --action Click --x 400 --y 300`.
+4. When `wait-for-debug-break` returns, inspect the frozen state with `uloop get-logs`, `uloop get-hierarchy`, or another focused uLoop inspection command.
+5. Resume PlayMode with `uloop control-play-mode --action Play` after inspection.
 
 ## Tool Reference