Skip to content

fix: Clarify transient debug-break guidance #1289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hatayama merged 8 commits into from
Jun 6, 2026
Merged

fix: Clarify transient debug-break guidance #1289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b013747
Translate wait-for-debug-break skill to Japanese
hatayama Jun 6, 2026
2f69e88
update skill
hatayama Jun 6, 2026
bb76bf3
Translate wait-for-debug-break skill back to English
hatayama Jun 6, 2026
9070d54
update skill
hatayama Jun 6, 2026
b8d687e
update skill
hatayama Jun 6, 2026
baa8490
skill update
hatayama Jun 6, 2026
783e7b0
update
hatayama Jun 6, 2026
4d1f53f
Sync wait-for-debug-break generated skills
hatayama Jun 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 9 additions & 22 deletions .agents/skills/uloop-wait-for-debug-break/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,8 @@
---
name: uloop-wait-for-debug-break
description: "Pause Unity at named checkpoints for frame-specific PlayMode bugs and transient input, physics, async, or UI state changes."
description: "Use this for Unity PlayMode/E2E checks when simulated input or gameplay events cause a state transition that a screenshot, durable state, or specific value log cannot prove. Pause at the natural transition point after the input/event is consumed and inspect the paused frame. Do not use simulate-* Success=true, generic action logs, sleeps/retries, testing-only counters, or Time.timeScale changes as substitutes for debug-break evidence of transient transitions."
---

# uloop wait-for-debug-break

Pause Unity when execution reaches a named marker in user code.

## When to use

- Use when a bug appears only on a specific frame, timing window, animation step, physics tick, or `Update` / `FixedUpdate` branch.
- Use proactively when PlayMode E2E or development debugging depends on proving a transient runtime state transition.
- Use it alongside screenshots and logs; it is not only for cases where screenshots fail.
- Good checkpoints include jump applied, launch complete, collision handled, score changed, line cleared, block mined, item placed, game over shown, or UI updated after input.
- If you use sleep, repeated polling, or a second state read to catch a transient PlayMode state, prefer `wait-for-debug-break` instead.

## Workflow

1. Add a marker at the state you want to inspect:
Expand All @@ -26,7 +14,7 @@ UnityCliLoopDebug.Break("player-jumped");
```

2. Compile the project.
3. Enable the marker before triggering the code path:
3. Enable the marker before triggering the target code path:

```bash
uloop enable-debug-break --id player-jumped --timeout-seconds 30
Expand All @@ -38,7 +26,7 @@ uloop enable-debug-break --id player-jumped --timeout-seconds 30
uloop debug-break-status --id player-jumped
```

5. Trigger the behavior, such as `simulate-keyboard`, `simulate-mouse-input`, UI interaction, or dynamic code.
5. Trigger the behavior with `simulate-keyboard`, `simulate-mouse-input`, UI interaction, dynamic code, or similar commands.
6. Wait for the marker:

```bash
Expand All @@ -54,18 +42,17 @@ If this command times out, the marker line was not reached while the command wai
uloop clear-debug-break --id player-jumped
```

## Marker placement
## Marker Placement

- Prefer natural gameplay or state-transition locations after input has been consumed, such as after jump velocity/state changes, physics contact, damage application, or inventory mutation.
- Prefer natural gameplay points or state-transition points after input has been consumed, such as after jump velocity or state changes, physics contact, or damage application.
- For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
- Enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return to avoid domain reload loss or tool Busy states.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect; immediate markers can interrupt the input command before the resulting gameplay state settles.
- To avoid Domain Reload loss or tool Busy states, enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect. Immediate markers can interrupt the input command before the resulting gameplay state settles.
- Use separate ids for strict phases, for example `jump-input-read`, `jump-velocity-applied`, and `jump-landed`, instead of reusing one broad marker.

## Safety

- `UnityCliLoopDebug.Break` uses Unity's conditional-call pattern and is compiled out of non-Editor call sites.
- Code in a custom asmdef must reference `UnityCLILoop.PausePoints.Runtime` to use `UnityCliLoopDebug.Break`.
- Do not pass side-effect expressions as the id argument. Use stable string ids.
- This does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable again after PlayMode starts.
- This feature does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable it again after PlayMode starts.
31 changes: 9 additions & 22 deletions .claude/skills/uloop-wait-for-debug-break/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,8 @@
---
name: uloop-wait-for-debug-break
description: "Pause Unity at named checkpoints for frame-specific PlayMode bugs and transient input, physics, async, or UI state changes."
description: "Use this for Unity PlayMode/E2E checks when simulated input or gameplay events cause a state transition that a screenshot, durable state, or specific value log cannot prove. Pause at the natural transition point after the input/event is consumed and inspect the paused frame. Do not use simulate-* Success=true, generic action logs, sleeps/retries, testing-only counters, or Time.timeScale changes as substitutes for debug-break evidence of transient transitions."
---

# uloop wait-for-debug-break

Pause Unity when execution reaches a named marker in user code.

## When to use

- Use when a bug appears only on a specific frame, timing window, animation step, physics tick, or `Update` / `FixedUpdate` branch.
- Use proactively when PlayMode E2E or development debugging depends on proving a transient runtime state transition.
- Use it alongside screenshots and logs; it is not only for cases where screenshots fail.
- Good checkpoints include jump applied, launch complete, collision handled, score changed, line cleared, block mined, item placed, game over shown, or UI updated after input.
- If you use sleep, repeated polling, or a second state read to catch a transient PlayMode state, prefer `wait-for-debug-break` instead.

## Workflow

1. Add a marker at the state you want to inspect:
Expand All @@ -26,7 +14,7 @@ UnityCliLoopDebug.Break("player-jumped");
```

2. Compile the project.
3. Enable the marker before triggering the code path:
3. Enable the marker before triggering the target code path:

```bash
uloop enable-debug-break --id player-jumped --timeout-seconds 30
Expand All @@ -38,7 +26,7 @@ uloop enable-debug-break --id player-jumped --timeout-seconds 30
uloop debug-break-status --id player-jumped
```

5. Trigger the behavior, such as `simulate-keyboard`, `simulate-mouse-input`, UI interaction, or dynamic code.
5. Trigger the behavior with `simulate-keyboard`, `simulate-mouse-input`, UI interaction, dynamic code, or similar commands.
6. Wait for the marker:

```bash
Expand All @@ -54,18 +42,17 @@ If this command times out, the marker line was not reached while the command wai
uloop clear-debug-break --id player-jumped
```

## Marker placement
## Marker Placement

- Prefer natural gameplay or state-transition locations after input has been consumed, such as after jump velocity/state changes, physics contact, damage application, or inventory mutation.
- Prefer natural gameplay points or state-transition points after input has been consumed, such as after jump velocity or state changes, physics contact, or damage application.
- For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
- Enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return to avoid domain reload loss or tool Busy states.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect; immediate markers can interrupt the input command before the resulting gameplay state settles.
- To avoid Domain Reload loss or tool Busy states, enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect. Immediate markers can interrupt the input command before the resulting gameplay state settles.
- Use separate ids for strict phases, for example `jump-input-read`, `jump-velocity-applied`, and `jump-landed`, instead of reusing one broad marker.

## Safety

- `UnityCliLoopDebug.Break` uses Unity's conditional-call pattern and is compiled out of non-Editor call sites.
- Code in a custom asmdef must reference `UnityCLILoop.PausePoints.Runtime` to use `UnityCliLoopDebug.Break`.
- Do not pass side-effect expressions as the id argument. Use stable string ids.
- This does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable again after PlayMode starts.
- This feature does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable it again after PlayMode starts.
31 changes: 9 additions & 22 deletions Packages/src/Editor/CliOnlyTools~/PausePoint/Skill/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,8 @@
---
name: uloop-wait-for-debug-break
description: "Pause Unity at named checkpoints for frame-specific PlayMode bugs and transient input, physics, async, or UI state changes."
description: "Use this for Unity PlayMode/E2E checks when simulated input or gameplay events cause a state transition that a screenshot, durable state, or specific value log cannot prove. Pause at the natural transition point after the input/event is consumed and inspect the paused frame. Do not use simulate-* Success=true, generic action logs, sleeps/retries, testing-only counters, or Time.timeScale changes as substitutes for debug-break evidence of transient transitions."
---

# uloop wait-for-debug-break

Pause Unity when execution reaches a named marker in user code.

## When to use

- Use when a bug appears only on a specific frame, timing window, animation step, physics tick, or `Update` / `FixedUpdate` branch.
- Use proactively when PlayMode E2E or development debugging depends on proving a transient runtime state transition.
- Use it alongside screenshots and logs; it is not only for cases where screenshots fail.
- Good checkpoints include jump applied, launch complete, collision handled, score changed, line cleared, block mined, item placed, game over shown, or UI updated after input.
- If you use sleep, repeated polling, or a second state read to catch a transient PlayMode state, prefer `wait-for-debug-break` instead.

## Workflow

1. Add a marker at the state you want to inspect:
Expand All @@ -26,7 +14,7 @@ UnityCliLoopDebug.Break("player-jumped");
```

2. Compile the project.
3. Enable the marker before triggering the code path:
3. Enable the marker before triggering the target code path:

```bash
uloop enable-debug-break --id player-jumped --timeout-seconds 30
Expand All @@ -38,7 +26,7 @@ uloop enable-debug-break --id player-jumped --timeout-seconds 30
uloop debug-break-status --id player-jumped
```

5. Trigger the behavior, such as `simulate-keyboard`, `simulate-mouse-input`, UI interaction, or dynamic code.
5. Trigger the behavior with `simulate-keyboard`, `simulate-mouse-input`, UI interaction, dynamic code, or similar commands.

@cubic-dev-ai cubic-dev-ai Bot Jun 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The new simulate-* guidance omits required Input System prerequisites (com.unity.inputsystem and Active Input Handling set to Input System Package (New) or Both), so the documented workflow can fail in otherwise valid projects.

(Based on your team's feedback about scoping simulate-* guidance to New Input System projects and documenting required Input Handling/package prerequisites.) .

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At Packages/src/Editor/CliOnlyTools~/PausePoint/Skill/SKILL.md, line 29:

<comment>The new simulate-* guidance omits required Input System prerequisites (`com.unity.inputsystem` and Active Input Handling set to `Input System Package (New)` or `Both`), so the documented workflow can fail in otherwise valid projects.

(Based on your team's feedback about scoping simulate-* guidance to New Input System projects and documenting required Input Handling/package prerequisites.) .</comment>

<file context>
@@ -38,7 +26,7 @@ uloop enable-debug-break --id player-jumped --timeout-seconds 30

-5. Trigger the behavior, such as simulate-keyboard, simulate-mouse-input, UI interaction, or dynamic code.
+5. Trigger the behavior with simulate-keyboard, simulate-mouse-input, UI interaction, dynamic code, or similar commands.
6. Wait for the marker:

</file context>


</details>

```suggestion
5. Trigger the behavior with `simulate-keyboard` or `simulate-mouse-input` (for projects using the New Input System with `com.unity.inputsystem` installed and Player Settings → Active Input Handling set to `Input System Package (New)` or `Both`), UI interaction, dynamic code, or similar commands.

6. Wait for the marker:

```bash
Expand All @@ -54,18 +42,17 @@ If this command times out, the marker line was not reached while the command wai
uloop clear-debug-break --id player-jumped
```

## Marker placement
## Marker Placement

- Prefer natural gameplay or state-transition locations after input has been consumed, such as after jump velocity/state changes, physics contact, damage application, or inventory mutation.
- Prefer natural gameplay points or state-transition points after input has been consumed, such as after jump velocity or state changes, physics contact, or damage application.
- For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
- Enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return to avoid domain reload loss or tool Busy states.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect; immediate markers can interrupt the input command before the resulting gameplay state settles.
- To avoid Domain Reload loss or tool Busy states, enable markers after Play Mode is running, and prefer checkpoints reached after the triggering input command can return.
- Avoid placing the marker immediately after issuing simulated input unless that exact input handling line is the state you need to inspect. Immediate markers can interrupt the input command before the resulting gameplay state settles.
- Use separate ids for strict phases, for example `jump-input-read`, `jump-velocity-applied`, and `jump-landed`, instead of reusing one broad marker.

## Safety

- `UnityCliLoopDebug.Break` uses Unity's conditional-call pattern and is compiled out of non-Editor call sites.
- Code in a custom asmdef must reference `UnityCLILoop.PausePoints.Runtime` to use `UnityCliLoopDebug.Break`.
- Do not pass side-effect expressions as the id argument. Use stable string ids.
- This does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable again after PlayMode starts.
- This feature does not collect logs or state snapshots. Use existing inspection commands after Unity pauses.
- If `enable-debug-break` warns about Domain Reload before PlayMode, the marker may be cleared when entering PlayMode. Domain Reload disabled is suitable for this workflow; otherwise enable it again after PlayMode starts.
Loading