name: runtime-process-debugging description: Debug cross-platform process, shell, sandbox, pipe, handle, startup, and shutdown behavior. Use for hangs, output loss, focus changes, lifecycle races, or platform-specific runtime failures. metadata: version: "1.0.1"

Runtime Process Debugging

Prove where lifecycle behavior diverges before changing it.

1. Map process ownership, parent/child relationships, pipe and handle owners,

cancellation, completion, and teardown.

1. Trace macOS, Linux, and Windows separately; do not assume their process or

pipe semantics match.

1. Instrument the narrow boundary where data, focus, or completion is lost.
2. Reproduce under the relevant scheduler, load, descendant-process, and EOF

conditions.

1. Fix the owning runtime layer, preserving intentional bounds such as avoiding

hangs from inherited handles.

1. Add a deterministic regression test that controls ordering explicitly; use

writing-tests for synchronization, pipe-drain, EOF, and assertion patterns.

Do not fix races with sleeps, retries, looser assertions, or larger timeouts unless evidence shows elapsed time is the intended contract. Prefer observable state—EOF, process exit, handle ownership, channel closure—over timing.

Related skills

• writing-tests: deterministic lifecycle regression tests. When invoked from

writing-tests, do not invoke it again.

• my-code-review: review a completed lifecycle fix and its regression test.