Use as the main entry for cosim debugging: gem5 crashes, assertions, hangs, timeouts, address translation faults, non-PASS test results, guest-side waits, and QEMU exits that may be secondary to gem5. Collect logs, preserve live state when needed, route to gem5 model references, and decide the first failing component.
Use when building gem5 or QEMU, checking build provenance, or preserving gem5 incremental builds across worktrees. Delegates to scripts/cosim_build.sh; never hand-roll Docker, scons, or QEMU make commands.
Use when delegating independent code review, design review, or focused bug investigation to an AI reviewer. Provides delegation templates and records reviewer evidence; higher-level review flow remains in cosim-gpu-review or cosim-gpu-rlcr-loop.
Use when the guest disk image needs modification without a full rebuild. Mount with guestmount, add files, systemd services, kernel module config.
Use as the first step for non-trivial cosim testing, debugging, review, or iterative implementation tasks. Do not use for ordinary repository maintenance such as commit splitting, submodule pointer updates, author config, or documentation-only cleanup.
Use when you need to send commands to a running cosim guest. Console pipe interaction, 9p share mount, GPU status check, manual driver load.
Use when collecting, summarizing, auditing, or comparing cosim evidence from artifact directories, large logs, matrices, verdict files, build provenance, or prior conversation records; also use when reducing raw log reads or checking whether existing artifacts lose information. Enforces full raw evidence preservation, bounded reads, source attribution, compact tables, raw-read plans, coverage self-reporting, and unknown-event preservation before analysis.
Use when you need to start the QEMU+gem5 cosim environment. Launches gem5 in Docker, QEMU with KVM on host, via vfio-user or legacy cosim socket.