/omh-native-debugging

name: "omh-native-debugging"
description: "[omh] Native program crashes or corrupts memory: prepare hypothesis-driven debugging of native binaries and instruct the executor to drive a DAP debugger instead of printf. Use when the user says: native-debugging, native debugging, native binary, segfault, segmentation fault, core dump, stack corruption, memory corruption."
metadata:
  hermes:
    tags: [workflow, oh-my-hermes, verification]
    category: verification
    phase: native-debugging
    role: reviewer
    quality_tier: native-debug-evidence-gated

Native Debugging

This is a Hermes-native `native-debugging` workflow skill.

Why This Exists

`native-debugging` closes OMH's zero-coverage low-level domain by preparing a hypothesis-driven, DAP-first debugging plan for native binaries, while OMH itself continues to execute nothing.

Do Not Use When

• The failure is a build or CI failure rather than a runtime fault in a binary; use `build-failure-triage`.
• The subject is an agent or workflow misbehaving rather than a native binary; use `agent-debug`.
• The wrong result, flaky test, or lost update is in application code such as a Python or TypeScript service and needs its root cause reproduced; use `app-debugging`.
• The change is Rust source work whose risk is `unsafe` or UB discipline; use `rust`.
• The request is to judge whether a fix is verified rather than to find the fault; use `verification-gate`.

Examples

Good example:

• Prompt: This binary segfaults on the third request; help me debug it.
• Expected behavior: Prepare native_fault_statement/v1, three competing hypotheses with distinguishing observations, and a debugger_session_plan/v1 naming the DAP adapter, breakpoints, and values to read.
• Why: The request is a runtime fault in a native binary where the plan, not the guess, is what OMH can prepare.

Bad example:

• Prompt: Add some printfs and tell me it is fixed once the crash stops.
• Expected behavior: Name the DAP-driven observation plan, and keep reproduction, root cause, and fix as separate not_observed states.
• Why: A disappearing symptom is not a root cause, and printf-via-rebuild is the fallback rather than the method.

Completion Checklist

• The fault is stated as an observed symptom with a reproduction command, separate from any assumed cause.
• At least three hypotheses span distinct axes and each carries its refuting observation.
• The debugger session plan names the DAP adapter, breakpoints, watchpoints, threads, frames, and values to read.
• The handoff says the executor drives the debugger and OMH executes nothing.
• Reproduction, debugger output, root cause, and fix are reported as separate observed or not_observed states.

Recovery Notes

• If the fault does not reproduce, make reproduction the first hypothesis and plan the observation that would establish it, rather than debugging a fault no one can trigger.
• If no debug adapter or symbols are available, say so, plan the coarser evidence path, and keep root cause unclaimed instead of upgrading a guess.

Workflow Lane

• Current lane: **Coding handoff** (`idea-to-deploy`, `llm-app-dev`, `cto-loop`, `deploy-and-monitor`, `code-review`, `build-failure-triage`, `verification-gate`, `security-safety-review`, `+28 more`) - coding owners, handoffs, review, CI, and merge evidence.
• If intent belongs to another lane, hand back to `oh-my-hermes` or name the adjacent workflow.
• Shared product, routing, compatibility, and evidence rules: `omh-routing/references/skill-common-rail.md`.

Use When

Use when Hermes should prepare low-level debugging of a native binary, crash, or memory fault: competing hypotheses, the distinguishing observation for each, and a DAP-driven evidence plan for the executor.

Strong routing signals: `native-debugging`, `native debugging`, `native binary`, `segfault`, `segmentation fault`, `core dump`, `stack corruption`, `memory corruption`, `heap corruption`, `use after free`, `null pointer dereference`, `stripped binary`, `disassembly`, `lldb`, `gdb`, `dap debugger`, `breakpoint`, `watchpoint`, `backtrace`, `セグメンテーション違反`, `コアダンプ`, `メモリ破壊`, `ヒープ破壊`, `解放後使用`, `逆アセンブル`, `네이티브 디버깅`, `세그폴트`, `코어 덤프`, `메모리 손상`, `역어셈블`, `중단점`, `段错误`, `核心转储`, `内存破坏`, `释放后使用`, `反汇编`

Catalog Metadata

Category: `verification` Phase: `native-debugging` Hermes role: `reviewer` Quality tier: `native-debug-evidence-gated` Reasoning demand: `standard`

Quality bar:

• State the fault as an observed symptom with its reproduction command before naming any cause.
• Load `references/native-debug-loop.md` and follow its hypothesis, observation, and escalation order rather than improvising a search.
• Write at least three hypotheses on distinct axes, each with the single observation that would refute it and the exact place to read that observation.
• Plan the debugger session concretely: adapter, breakpoints, watchpoints, threads, frames, and the values read at each stop — the executor should not have to invent the session.
• Prefer debugger-observed state over added print statements; a rebuild-and-print loop is the fallback, not the method.
• Keep reproduction, debugger output, root cause, and fix as separate observed states.

Handoff policy:

Keep the fault statement, hypothesis set, distinguishing observations, and the debugger plan in Hermes. Record every breakpoint hit, register or memory read, backtrace, and reproduction only from executor or wrapper observed evidence.

Required inputs:

• the binary, crash signature, or fault symptom
• whether source and debug symbols are available
• platform, architecture, and the reproduction command
• how reliably the fault reproduces
• existing crash logs, core dumps, or sanitizer output
• observed debugger evidence for any resolution claim

Expected outputs:

• native_fault_statement/v1
• hypothesis_set/v1 with at least three competing hypotheses
• distinguishing_observation_plan/v1
• debugger_session_plan/v1
• native_debug_handoff/v1
• ob