Runtime Process Debugging
Prove where lifecycle behavior diverges before changing it.
- Map process ownership, parent/child relationships, pipe and handle owners,
cancellation, completion, and teardown.
- Trace macOS, Linux, and Windows separately; do not assume their process or
pipe semantics match.
- Instrument the narrow boundary where data, focus, or completion is lost.
- Reproduce under the relevant scheduler, load, descendant-process, and EOF
conditions.
- Fix the owning runtime layer, preserving intentional bounds such as avoiding
hangs from inherited handles.
- 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.code-review: review a completed lifecycle fix and its regression test.
1---2name: runtime-process-debugging3description: 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.4---56# Runtime Process Debugging78Prove where lifecycle behavior diverges before changing it.9101. Map process ownership, parent/child relationships, pipe and handle owners,11 cancellation, completion, and teardown.122. Trace macOS, Linux, and Windows separately; do not assume their process or13 pipe semantics match.143. Instrument the narrow boundary where data, focus, or completion is lost.154. Reproduce under the relevant scheduler, load, descendant-process, and EOF16 conditions.175. Fix the owning runtime layer, preserving intentional bounds such as avoiding18 hangs from inherited handles.196. Add a deterministic regression test that controls ordering explicitly; use20 `writing-tests` for synchronization, pipe-drain, EOF, and assertion patterns.2122Do not fix races with sleeps, retries, looser assertions, or larger timeouts23unless evidence shows elapsed time is the intended contract. Prefer observable24state—EOF, process exit, handle ownership, channel closure—over timing.2526## Related skills2728- `writing-tests`: deterministic lifecycle regression tests. When invoked from29 `writing-tests`, do not invoke it again.30- `code-review`: review a completed lifecycle fix and its regression test.
caarlos0