chore: Improve uloop skill guidance for frame debugging

Packages/src/Editor/CliOnlyTools~/PausePoint/Skill/SKILL.md

@@ -1,54 +1,63 @@
 ---
 name: uloop-wait-for-debug-break
-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."
+description: "Use this like an IDE breakpoint for Unity PlayMode/E2E when you need to pause a specific frame and inspect variables, GameObjects, or runtime state."
 ---
 
-## Workflow
+## Quick Check Template
 
-1. Add a marker at the state you want to inspect:
+Use this small loop for one representative frame you care about:
+
+1. Put a focused log and marker at the natural transition point. Log only local/intermediate values that will be hard to inspect later:
 
 ```csharp
+using UnityEngine;
 using io.github.hatayama.UnityCliLoop.Runtime;
 
-UnityCliLoopDebug.Break("player-jumped");
+Debug.Log($"state-transition-applied localValue={localValue} reason={reason}");
+UnityCliLoopDebug.Break("state-transition-applied");
 ```
 
-2. Compile the project.
-3. Enable the marker before triggering the target code path:
+2. Compile, enter PlayMode, then enable the marker:
 
 ```bash
-uloop enable-debug-break --id player-jumped --timeout-seconds 30
+uloop enable-debug-break --id state-transition-applied --timeout-seconds 30
 ```
 
-4. Check marker state if needed:
+3. Trigger the action with a `simulate-*` command.
+4. Run `uloop wait-for-debug-break --id state-transition-applied --timeout-seconds 30`, even if the trigger command already returned `InterruptedByDebugBreak=true`.
+5. Before resuming, read the focused log for the same marker id:
 
 ```bash
-uloop debug-break-status --id player-jumped
+uloop get-logs --search-text state-transition-applied --max-count 20
 ```
 
-5. Trigger the behavior with `simulate-keyboard`, `simulate-mouse-input`, UI interaction, dynamic code, or similar commands.
-6. Wait for the marker:
+6. While Unity is still paused, capture any additional evidence with `uloop execute-dynamic-code`, `uloop get-hierarchy`, `uloop find-game-objects`, and one screenshot.
+7. Clear the marker with `uloop clear-debug-break --id state-transition-applied` or stop PlayMode before moving on.
 
-```bash
-uloop wait-for-debug-break --id player-jumped --timeout-seconds 30
-```
+## When To Use
 
-If this command times out, the marker line was not reached while the command waited. Inspect `error.details.status`, `hitCount`, `isPlaying`, `isPaused`, `elapsedSinceEnabledMilliseconds`, and `remainingMilliseconds` to distinguish input not being consumed, gameplay conditions not being met, an id mismatch, or Unity already being paused. `elapsedSinceEnabledMilliseconds` is measured from `enable-debug-break`, not from `wait-for-debug-break`.
+- Use this as the standard frame proof for state-changing PlayMode/E2E simulated input, physics, or UI transitions.
+- Pause at least one representative transition per E2E pass, even if durable state, logs, or screenshots can later confirm the final result.
+- Use this before reaching for `Time.timeScale`, sleeps, repeated polling, or after-the-fact `execute-dynamic-code`; those checks can supplement the paused-frame proof, but they are not substitutes.
+- If the value you need is a method local, an intermediate calculation, or a branch reason that `execute-dynamic-code` cannot reach, add a focused `Debug.Log` immediately before the marker and read it with `get-logs` while paused. Do not count the breakpoint check complete until the matching log has been read.
+- Good pause points include after input is consumed, a command is accepted, a state mutation is committed, an evaluation step resolves, a tracked value changes, a UI/domain state syncs, or a success/failure/end condition is entered.
+- Treat the pause like a lightweight breakpoint for one important transition: combine nearby debug logs with paused-frame inspection to confirm the variables and component state at that point.
+- Do not treat `simulate-* Success=true`, generic action logs, sleeps/retries, testing-only counters, or `Time.timeScale` changes as paused-frame proof.
+- Skip this only for ordinary persistent-state checks when you are not validating simulated input delivery, event ordering, or transition-frame fidelity.
 
-7. While Unity is paused, inspect state with `uloop get-logs`, `uloop get-hierarchy`, `uloop find-game-objects`, screenshots, or `uloop execute-dynamic-code`.
-8. Clear the marker if you stop waiting:
+## Timeout Checks
 
-```bash
-uloop clear-debug-break --id player-jumped
-```
+If this command times out, the marker line was not reached while the command waited. Inspect `error.details.status`, `hitCount`, `isPlaying`, `isPaused`, `elapsedSinceEnabledMilliseconds`, and `remainingMilliseconds` to distinguish input not being consumed, runtime conditions not being met, an id mismatch, or Unity already being paused. `elapsedSinceEnabledMilliseconds` is measured from `enable-debug-break`, not from `wait-for-debug-break`.
+
+Use `uloop debug-break-status --id state-transition-applied` only when you need to confirm the marker is armed or inspect the current hit state. Add focused debug logs before the marker when local variables must be captured.
 
 ## Marker Placement
 
-- 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.
+- Prefer natural runtime points after input has been consumed, such as after a command is accepted, a state value changes, an evaluation step resolves, or a dependent component is updated.
 - For frame-specific bugs, place the marker on the suspicious state branch or immediately after the state mutation you need to freeze.
 - 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.
+- 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 runtime state settles.
+- Use separate ids for strict phases, for example `input-read`, `state-updated`, and `result-committed`, instead of reusing one broad marker.
 
 ## Safety
 

Packages/src/Editor/FirstPartyTools/ExecuteDynamicCode/Skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uloop-execute-dynamic-code
 toolName: execute-dynamic-code
-description: "Execute C# with Unity APIs when existing uloop tools cannot inspect or edit enough. Use for scene, prefab, SerializedObject, AssetDatabase refresh/.meta generation, menu, or PlayMode automation."
+description: "Execute C# with Unity APIs when existing uloop tools cannot inspect or edit enough. Use for reachable scene/component state, scene/prefab/menu automation, and PlayMode checks"
 context: fork
 ---
 
@@ -11,6 +11,8 @@ Execute the following request using `uloop execute-dynamic-code`: $ARGUMENTS
 
 For basic selected GameObject discovery or property inspection, use `find-game-objects --search-mode Selected` before this tool. Use this tool after the built-in inspection tools are not enough or when you need to modify Unity state.
 
+This tool can inspect reachable Unity state, such as GameObjects, components, public properties, static values, and method results. It cannot directly read local variables or intermediate calculations inside an already-running method. When those values matter, add a focused `Debug.Log` immediately before `UnityCliLoopDebug.Break("<id>")`, then run `get-logs --search-text <id>` while Unity is paused. Do not replace that log read with execute-dynamic-code.
+
 ## Workflow
 
 1. Read the relevant reference file(s) from the Code Examples section below

Packages/src/Editor/FirstPartyTools/GetLogs/Skill/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: uloop-get-logs
 toolName: get-logs
-description: "Read current Unity Console entries from a running Editor. Use during bug investigation after compile, tests, PlayMode, or dynamic code to inspect logs, warnings, errors, and stack traces."
+description: "Read current Unity Console entries from a running Editor. Use during bug investigation after compile, tests, PlayMode, dynamic code, or immediately after `uloop-wait-for-debug-break`."
 ---
 
 # uloop get-logs
 
 Retrieve logs from Unity Console.
 
+When a debug-break marker pauses Unity and the value you need is a method local, intermediate calculation, or branch reason, read the focused `Debug.Log` entry added immediately before the marker before resuming PlayMode. Use `--search-text <marker-or-id>` so the marker and its log are checked as one breakpoint-style proof.
+
 ## Usage
 
 ```bash

Packages/src/Editor/FirstPartyTools/SimulateKeyboard/Skill/SKILL.md

@@ -12,10 +12,10 @@ Simulate keyboard input on Unity PlayMode: $ARGUMENTS
 ## Workflow
 
 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. If the screenshot cannot prove the gameplay state, place and enable a `UnityCliLoopDebug.Break("<id>")` marker with `uloop enable-debug-break`, run the input again, then inspect while Unity is paused
-5. Report what happened
+2. Execute the needed `uloop simulate-keyboard` commands
+3. Inspect the result with the lightest useful evidence: runtime state, logs, or a screenshot
+4. If exact-frame proof would reduce uncertainty, treat Debug Break inspection as an optional follow-up using the section below
+5. Report what happened and which evidence was used
 
 ## Tool Reference
 
@@ -39,17 +39,19 @@ uloop simulate-keyboard --action <action> --key <key> [options]
 | `KeyDown` | KeyDown only (held until KeyUp) | Start continuous movement, hold sprint |
 | `KeyUp` | KeyUp only (release held key) | Stop movement, release sprint |
 
-Use `Press` for edge-triggered gameplay code such as `Keyboard.current.spaceKey.wasPressedThisFrame`.
+Use `Press` for edge-triggered keyboard code such as `Keyboard.current.spaceKey.wasPressedThisFrame`.
 `KeyDown` emits one initial press edge, then only keeps the key held. It does not keep `wasPressedThisFrame` true while the key remains held.
-If a successful `Press` or `KeyDown` leaves `Keyboard.current.<key>.isPressed` true but the game state does not change, do not immediately rewrite the user's gameplay code to `isPressed`. First verify that the gameplay component is active during the command, that it polls input in the configured Input System update phase, and that a missed `KeyDown` edge is followed by `KeyUp` before retrying.
+If a successful `Press` or `KeyDown` leaves `Keyboard.current.<key>.isPressed` true but runtime state does not change, do not immediately rewrite the user's runtime code to `isPressed`. First verify that the target component is active during the command, that it polls input in the configured Input System update phase, and that a missed `KeyDown` edge is followed by `KeyUp` before retrying.
 Use `KeyDown` / `KeyUp` when the scenario intentionally needs a held key.
 
-### Debug Break verification
+### Optional Debug Break Inspection
 
-- Use `UnityCliLoopDebug.Break("<id>")` when a screenshot cannot prove that the keyboard input changed gameplay state, such as jump, sprint, or interaction.
-- Put the marker at a natural state transition after the game consumed the key, such as after jump velocity is applied, not immediately after sending `simulate-keyboard`.
+- Use `UnityCliLoopDebug.Break("<id>")` with `uloop-wait-for-debug-break` only when exact-frame evidence would reduce uncertainty. Final logs, screenshots, or durable state may be enough for simpler checks.
+- Put the marker at a natural state transition after the app consumed the key, such as after a command is accepted, a state mutation is committed, an evaluation step resolves, or a dependent component is updated. Do not place it immediately after sending `simulate-keyboard`.
+- If the key handler has local variables, intermediate calculations, or branch reasons that `execute-dynamic-code` cannot inspect after the fact, log just those values near `UnityCliLoopDebug.Break("<id>")` and read them with `uloop-get-logs` while Unity is paused. A break hit proves the line was reached, not the frame-local values.
+- Treat `simulate-keyboard Success=true`, generic action logs, and final durable counters as useful evidence, but not as paused-frame proof.
 - If the response has `InterruptedByDebugBreak: true`, Unity is paused for inspection and the tool released its held input bookkeeping. If a `UnityCliLoopDebug.Break` marker caused the pause, `DebugBreakId` and `DebugBreakHitCount` identify it. Use `get-logs`, `get-hierarchy`, `find-game-objects`, or `execute-dynamic-code` before resuming.
-- Use distinct marker ids for strict phases, for example `jump-key-read` and `jump-velocity-applied`.
+- Use distinct marker ids for strict phases, for example `input-read`, `state-updated`, and `result-committed`.
 
 ### KeyDown/KeyUp Rules
 
@@ -68,16 +70,16 @@ Use `KeyDown` / `KeyUp` when the scenario intentionally needs a held key.
 ## Examples
 
 ```bash
-# One-shot key press (tap W once)
+# One-shot key press
 uloop simulate-keyboard --action Press --key W
 
-# Jump (tap Space)
+# One-shot action key
 uloop simulate-keyboard --action Press --key Space
 
-# Hold W for 2 seconds (move forward)
+# Hold a key for 2 seconds
 uloop simulate-keyboard --action Press --key W --duration 2.0
 
-# Sprint forward (hold Shift + W, then release)
+# Hold two keys, then release them
 uloop simulate-keyboard --action KeyDown --key LeftShift
 uloop simulate-keyboard --action KeyDown --key W
 uloop screenshot --capture-mode rendering