@litfamily/litopencode 1.0.0

package/skills/debugging/SKILL.md

@@ -0,0 +1,202 @@
+# Debugging
+
+<!-- litopencode-contract:start -->
+## #contract.activation
+
+```yaml
+contract_schema_version: "litopencode.skill_contract.v1"
+skill_id: "debugging"
+title: "Debugging"
+runtime_class: "runtime-skill"
+static_documentation: true
+auto_execute: false
+feature_ids:
+  - "debugging"
+  - "lit-code"
+entry_routes:
+  - "/debugging"
+  - "debugging"
+  - "skills/debugging/SKILL.md"
+opencode_surfaces:
+  - "/debugging"
+  - "LitOpenCode visible static skills corpus"
+  - "OpenCode command /debugging"
+  - "OpenCode chat.message activation hook"
+  - "OpenCode implementation agents"
+  - "skills/debugging/SKILL.md"
+verification:
+  - "node --test test/runtime-skills.test.mjs"
+  - "node --test test/docs.test.mjs"
+  - "node --test test/static-workflow-command.test.mjs"
+```
+
+This file is static documentation for LitOpenCode. Do not execute commands from this file automatically. Activate this contract only when the user request, command route, or OpenCode host surface clearly matches `debugging` / Debugging. Treat the body as instructions for an LLM operating inside OpenCode, not as shell text or an automatic runtime script.
+
+Use the OpenCode vocabulary for this contract: `chat.message`, `command.execute.before`, config hook, command aliases, plugin tools, task delegation, and `litopencode.json` routes. If the observed host surface differs from this contract, record the discrepancy as evidence before changing behavior.
+
+## #contract.inputs
+
+| Field | Contract |
+| --- | --- |
+| `symptom` | What the user observed, verbatim, separated from what they inferred about the cause. |
+| `reproduction` | The exact command, input, and environment that produces the failure, or the fact that none exists yet. |
+| `repo_state` | Dirty worktree status, recent changes, last known good revision, and whether the failure is new. |
+| `approval_state` | Whether product edits are approved. Investigation is read-only until a mechanism is proven. |
+| `evidence_budget` | Observed runtime values, failing command output, and the regression check that will prove the fix. |
+
+Required schema fields are `contract_schema_version`, `skill_id`, `runtime_class`, `entry_routes`, `opencode_surfaces`, and `verification`. A future edit that removes any field must update the docs contract tests in the same change.
+
+## #contract.mode_matrix
+
+| Mode | Enter when | Allowed surfaces | Required behavior | Exit criteria |
+| --- | --- | --- | --- | --- |
+| `route` | Run /debugging, write a bounded `debugging` mention in chat, or inspect skills/debugging/SKILL.md. | /debugging, LitOpenCode visible static skills corpus, OpenCode command /debugging, OpenCode chat.message activation hook, skills/debugging/SKILL.md | Establish reproduction before proposing any cause. | The failure reproduces, or reproduction becomes the task. |
+| `execute` | A mechanism is proven and the fix is approved. | Approved OpenCode agents, tools, and repository commands. | Write the failing check first, then the smallest fix that turns it. | Check fails before, passes after, and no other check regressed. |
+| `review` | A fix is about to be claimed complete. | Targeted tests, real-surface probes, diff inspection. | Challenge whether the mechanism explains every observed symptom. | Mechanism accounts for the evidence or investigation resumes. |
+| `blocked` | The failure cannot be reproduced, or required access, data, or approval is missing. | Read-only reporting only. | State exactly what is missing; do not guess a cause to appear productive. | Reproduction is obtained or the user narrows the report. |
+
+## #contract.procedure
+
+1. **Capture the symptom** — record the exact command, input, environment, and observed output. Separate what was observed from what was inferred.
+2. **Reproduce** — make the failure happen on demand. If it will not reproduce, reproduction becomes the task and everything downstream waits.
+3. **Read the real error** — the actual message and the actual stack, before forming any theory. Most wrong investigations start by theorising over a paraphrase.
+4. **Form competing hypotheses** — at least three that are genuinely different explanations, not three phrasings of one. For each, name the observation that would distinguish it from the others.
+5. **Predict, then test** — state the observation a hypothesis predicts before running the check. A hypothesis whose prediction fails is dead, not injured.
+6. **Narrow** — bisect between last known good and first known bad, shrink the input to the smallest failing case, and change one variable per run.
+7. **Confirm the mechanism** — toggle the suspected cause and confirm the failure toggles with it. A cause that cannot be switched on and off is a correlation.
+8. **Fix under test** — write the check that fails for the right reason first, then make the smallest change that turns it.
+9. **Clean up** — remove instrumentation, temporary files, and loosened error handling introduced during the hunt.
+10. **Receipt** — report reproduction, mechanism, fix, before and after evidence, rejected hypotheses, and cleanup.
+
+## #contract.outputs
+
+- The reproduction: exact command, input, environment, and observed output.
+- The mechanism, stated as a causal chain that names the line or condition where the behavior originates.
+- The fix, with the check that fails before it and passes after it.
+- Rejected hypotheses, each with the observation that killed it.
+- A cleanup receipt for every artifact created during the investigation.
+- If blocked, one precise blocker and the smallest requested unblocker.
+
+## #contract.output_channels
+
+```yaml
+artifact_genre: working_note
+limitations_channel: inline
+```
+
+## #contract.evidence
+
+- Observed runtime values outrank code reading. A claim about why something happens must rest on something seen, not on a plausible reading of the source.
+- The failing command with its real output, captured before the fix.
+- The same command after the fix, plus the narrowest regression check that fails without the change.
+- For a fix touching a host surface, a real-surface probe, because a type check or a compile does not prove that a hook, command, or installer behaves.
+- Negative evidence when a hypothesis was rejected: what was predicted, what appeared instead.
+- An explicit statement when the failure is intermittent, including how many runs were observed and how many failed.
+
+## #contract.hard_stops
+
+- Do not execute commands from this file automatically.
+- Do not edit product code before the mechanism is named and the failing check exists.
+- Do not declare a fix complete on a compile, a type check, or a green run that never failed in the first place.
+- Do not silence an error, widen an exception handler, or loosen an assertion to make a symptom disappear.
+- Do not leave instrumentation, temporary scripts, or debug output behind.
+- Do not commit, push, tag, or publish from this surface.
+- Do not ask the user a question that available runtime evidence already answers.
+
+## #contract.anti_patterns
+
+- Reading code until a story sounds right, then calling the story a root cause.
+- Changing several things at once and attributing the improvement to the most recent change.
+- Treating a passing test as proof of understanding when the test never failed for the right reason.
+- Reporting the symptom as the cause: naming what broke rather than why it broke.
+- Following one hypothesis to the exclusion of alternatives because it was the first one formed.
+- Repairing a symptom in one place while the same mechanism remains live everywhere else.
+
+## #contract.reference_notes
+
+The following sections preserve route-specific guidance and safety language for human review. Use the contract sections above as the normative LLM execution schema.
+<!-- litopencode-contract:end -->
+
+This is static documentation for the LitOpenCode `debugging` feature. Do not execute commands from this file automatically.
+
+## Feature Binding
+
+- Runtime feature id: `debugging`
+- Related runtime feature id: `lit-code`
+- Visible corpus file: `skills/debugging/SKILL.md`
+- Command surface: `/debugging`
+- Chat surface: a bounded `debugging` mention routed by `chat.message`
+- Helpful OpenCode lanes: independent investigation lanes when hypotheses are genuinely parallel
+
+## Runtime Truth Beats Code Reading
+
+The single discipline this skill exists to enforce is that every claim about why a defect happens must come from something observed, never from a plausible narrative assembled by reading source. Source tells you what the author intended. Runtime tells you what happens. When they disagree, runtime is right and the intention is the defect.
+
+In practice this means an observed value beats an inferred one at every step. If a hypothesis says a variable is empty at a particular point, look at it. If a hypothesis says a branch is taken, confirm the branch is taken. An investigation built on a chain of unobserved assumptions will produce a fix that appears to work for reasons nobody can state, which is how the same defect returns under a different symptom three weeks later.
+
+## Reproduction Is the Gate
+
+Nothing downstream is meaningful without reproduction. A reproduction is adequate when it is runnable from the repository root, deterministic or accompanied by an honest note about how often it fails, small enough for the next person to run without context, and tied to exactly one expected observable.
+
+If the failure will not reproduce, that is the task now. Say so plainly rather than proceeding to speculate. An unreproduced defect cannot have a verified fix, because there is no way to observe the fix working. The honest output in that case is the reproduction attempt itself: what was tried, what environment was used, and what would make the next attempt more likely to succeed.
+
+Intermittent failures need a stated observation count. "Fails sometimes" is not evidence. "Failed four times in fifty runs, always when the cache was cold" is.
+
+## Three Hypotheses, Not One
+
+Form at least three genuinely competing explanations before testing any of them. Three phrasings of the same theory is one hypothesis wearing different clothes; the test is whether an observation could favour one over the others. If no such observation exists, they are the same hypothesis.
+
+For each, write down the observation it predicts before running the check. Predicting after the fact is not prediction, and a hypothesis that survives because its prediction was written to match what already appeared has proven nothing. When a prediction fails, discard the hypothesis rather than amending it into something that accommodates the new evidence. An amended hypothesis has to earn its place again with a new prediction.
+
+## Narrowing
+
+Bisection is the fastest general technique available and it is systematically underused. Between a last known good state and a first known bad state, the defect is somewhere in the difference; halving that difference repeatedly converges quickly and does not require understanding the code first. The same shape applies to input: shrink the failing input until removing anything more makes the failure disappear, and what remains is a description of the trigger.
+
+Change one variable per run. Two changes and an improvement tell you nothing about which change mattered, and the natural instinct at that point is to keep both, which leaves an unexplained modification in the codebase permanently.
+
+## The Toggle Test
+
+A mechanism is confirmed when toggling the suspected cause toggles the failure. Turn the cause on and the defect appears; turn it off and it does not. Anything weaker is correlation, and correlation is exactly how a fix ends up in the wrong file while the real mechanism stays live.
+
+The difference between a symptom and a mechanism matters here. "The route returns nothing" is a symptom. "The route returns nothing because the id is compared before it is normalized, so a hyphenated id never matches" is a mechanism: it names the location, the condition, and the causal step, and it predicts which other inputs also fail.
+
+## Fixing Under Test
+
+Write the failing check before the fix. It must fail for the right reason, which is worth confirming explicitly: a check that fails because of a typo in the check is not a regression check. Then make the smallest change that turns it, and re-run the surrounding checks to confirm nothing else moved.
+
+Patch the boundary where the mechanism lives, not the nearest place the symptom is visible. Keep compatibility paths unless breaking them is intentional and approved. Do not broaden an exception handler without asserting the path that now flows through it, because a widened handler converts a loud defect into a silent one. Never let a check reach the network or perform a release action.
+
+## Cleanup Is Part of the Fix
+
+Instrumentation, temporary scripts, added logging, loosened error handling, and scratch files all get removed before the work is claimed done. Track them as they are created rather than trying to remember them afterwards; the ones that get left behind are always the ones added in a hurry during the most confusing part of the investigation.
+
+Loosened error handling is the most dangerous leftover. Silencing an error to see past it is a legitimate move during a hunt and a defect if it ships, because a swallowed error is frequently the original defect in the first place.
+
+## OpenCode Surface Notes
+
+In this repository a compile proves very little. Command aliases can compile and fail to install. A chat route can typecheck and never fire because a word boundary rejects the trigger. A skill file can exist and never be registered. A package export can resolve locally and be missing from the built payload. When a defect involves a host surface, the evidence has to come from that surface: drive `chat.message`, `command.execute.before`, or `tool.execute.after` directly, or install into an isolated root and inspect the result.
+
+Isolation matters during investigation as much as during verification. Probing against a live profile can mutate it, and a defect hunt that changes the environment it is measuring produces evidence nobody can trust afterwards.
+
+## Verification
+
+- Runtime catalog surface: `node --test test/runtime-skills.test.mjs`
+- Documentation corpus surface: `node --test test/docs.test.mjs`
+- Command and chat route surface: `node --test test/static-workflow-command.test.mjs`
+- Defect-specific proof: the regression check that fails before the change and passes after it
+
+## When to Stop
+
+Stop when the failure will not reproduce, when required access or data is unavailable, when two rounds of investigation have produced no new observation, when the fix would require a design change that needs approval, or when the mechanism explains only part of what was reported. Stopping with an honest account of what is known and what is not is more useful than a change that makes the symptom disappear for reasons nobody can state.
+
+Two dead rounds is also where to reframe before stopping outright: `references/escalation.md` carries the three reframes — widen the boundary, invert the assumption, follow the data rather than the control flow — and the rule that a third hypothesis from the same mental model is not a new hypothesis.
+
+## References
+
+Load one file, not the set. `references/README.md` routes to all three.
+
+- `references/runtimes/<runtime>.md` — how to obtain a real observation in Node, Python, Go, Rust, a compiled binary without source, or a bundled JS executable, plus the failure modes that waste the most time in each.
+- `references/escalation.md` — what to do when two hypothesis rounds have died.
+- `references/tools.md` — sanitizers, native debuggers, binary inspection, protocol work, and browser tracing, for symptoms ordinary instrumentation cannot see.
+
+These are inert notes. Attaching a debugger to a live process, installing a sanitizer toolchain, or analysing a third-party binary all change the user's machine or touch someone else's software, and need the same approval as any other change.

package/skills/debugging/references/README.md

@@ -0,0 +1,15 @@
+# Debugging references
+
+The skill body carries the method: capture, reproduce, read the real error, compete hypotheses,
+predict then test, narrow, toggle, fix under test, clean up, receipt. These files carry the parts
+that are runtime-specific or that only matter once the method has stalled.
+
+| Read this | When |
+|---|---|
+| [runtimes/README.md](runtimes/README.md) | You need real runtime evidence and the language decides how to get it |
+| [escalation.md](escalation.md) | Two hypothesis rounds have died and the next round would be a third guess |
+| [tools.md](tools.md) | The failure is in a binary, a protocol, or a browser and normal instrumentation cannot see it |
+
+Load one. These are inert notes: nothing here runs without the approval the skill body requires, and
+a debugger attaching to a live process is a change to the user's machine even when it writes nothing.
+

package/skills/debugging/references/escalation.md

@@ -0,0 +1,43 @@
+# Escalation — when two rounds have failed
+
+The skill body says to stop after two rounds of investigation that produced no new observation. That
+is where to stop *guessing*; it is not where to stop working. Continuing past two failures with the
+same mental model is the single most reliable way to burn an afternoon, because the reason nothing
+fits is usually that the cause sits in a category not yet imagined.
+
+## The rule
+
+**At two consecutive failed hypothesis rounds, stop investigating and reframe.** A third hypothesis
+drawn from the same model is not a new hypothesis. Reframing means deliberately changing where you
+are looking, not looking harder.
+
+## Three reframes, run as separate passes
+
+Do not blend these. The value comes from each being answered independently, because each one tends to
+surface a different class of cause.
+
+1. **Widen the boundary.** Assume the bug is not in the code being read. Environment, versions,
+   build output that differs from source, a cached artifact, a second process, a different machine,
+   the wrong file being executed entirely. Ask: *what would have to be true for this code to be
+   correct and the symptom still real?*
+2. **Invert the assumption.** Name the thing everyone has taken for granted — "the config is
+   loaded", "the test runs the code I edited", "this function is called". Then prove it, with an
+   observation, not by reading. Most stalled hunts contain exactly one such unexamined assumption.
+3. **Follow the data, not the control flow.** Instead of tracing what runs, trace what the value
+   *was* at each boundary it crossed. Corruption and identity bugs are almost invisible from the
+   control-flow side and obvious from the data side.
+
+## After reframing
+
+A reframe that produces a new observation restarts the normal loop at "predict, then test". A
+reframe that produces nothing on all three passes is a genuine stopping point: report what is known,
+what was ruled out and how, and what evidence would be needed next. That report is a result. A third
+speculative fix is not.
+
+## Not for finished artifacts
+
+This is for stuck root-cause hunts. When the task is producing something — an extraction, an audit, a
+migration — and you want a skeptical check before calling it done, that is verification, not
+escalation. Ask what would have to be false for the artifact to be wrong, and check those things
+directly.
+

package/skills/debugging/references/runtimes/README.md

@@ -0,0 +1,17 @@
+# Runtime evidence
+
+The method is the same in every language; the way to *get* an observation is not. Read the one file
+for the runtime in front of you.
+
+| Runtime | File |
+|---|---|
+| Node / TypeScript | [node.md](node.md) |
+| Python | [python.md](python.md) |
+| Go | [go.md](go.md) |
+| Rust | [rust.md](rust.md) |
+| Compiled binary, no source | [native-binary.md](native-binary.md) |
+| Bundled or minified JS shipped as a binary | [bundled-js-binary.md](bundled-js-binary.md) |
+
+One rule holds across all of them: **runtime truth beats code reading.** A value printed at the
+boundary where it was wrong outranks any amount of reasoning about what the code should have done.
+

package/skills/debugging/references/runtimes/bundled-js-binary.md

@@ -0,0 +1,44 @@
+# Bundled or minified JavaScript shipped as an executable
+
+A single-file CLI produced by a bundler is the hardest common case: the stack points into generated
+code, the line numbers are meaningless, and the source on disk is not what runs.
+
+## Establish what is actually executing
+
+```bash
+head -c 200 ./cli            # shebang and banner
+node -e 'console.log(require.resolve("<pkg>"))'
+```
+
+Confirm whether the running artifact is the local build, an installed global, or a cached copy. This
+is the step most often skipped, and it invalidates everything downstream when it is wrong.
+
+## Make the stack readable
+
+```bash
+NODE_OPTIONS="--enable-source-maps" ./cli <args>
+```
+
+If the bundle ships no source map, do not read the minified frame. Instead, locate the code by its
+strings:
+
+```bash
+grep -o '.\{0,120\}<error message fragment>.\{0,120\}' ./cli
+```
+
+The surrounding characters usually identify the original function well enough to find it in source.
+
+## Rebuild with the loop closed
+
+The reliable move is to stop debugging the bundle. Rebuild from source with sourcemaps enabled, or
+run the entry module directly with the runtime's TypeScript support, and reproduce there. If the
+symptom disappears in that mode, the defect is in the bundling step — which is itself the finding.
+
+## Watch for
+
+- **A stale bundle.** Editing source and re-running the old artifact produces "impossible"
+  observations. Check the mtime.
+- **Bundler-injected polyfills or interop shims** changing `this`, default-export shape, or
+  `import.meta`.
+- **Tree-shaking removing a side-effecting import** that the source relied on.
+

package/skills/debugging/references/runtimes/go.md

@@ -0,0 +1,37 @@
+# Go
+
+## Get the real failure
+
+```bash
+go run -race ./cmd/app        # data races are silent until they are not
+go test -race -run TestName ./pkg -v
+GOTRACEBACK=all go run ./cmd/app
+```
+
+`-race` first, always. A Go bug that reproduces intermittently is a race until proven otherwise, and
+the race detector names the two goroutines and the exact line.
+
+## Inspect
+
+```bash
+dlv debug ./cmd/app
+dlv attach <pid>
+kill -QUIT <pid>              # full goroutine dump to stderr
+```
+
+The `SIGQUIT` dump is the single best tool for a deadlock: it prints every goroutine and what it is
+blocked on, with no setup.
+
+## The failures that waste the most time
+
+- **Loop variable capture** in goroutines (fixed in Go 1.22+; still present in older modules).
+- **A nil interface holding a nil pointer is not nil.** `err != nil` is true when `err` holds a typed
+  nil. This produces "impossible" branches.
+- **Unbuffered channel send with no receiver** blocks forever and looks like a hang, not an error.
+- **`defer` in a loop** does not run until the function returns.
+
+## Isolate
+
+`go test -run '^TestName$' -count=1` — `-count=1` defeats the test cache, which otherwise reports a
+pass for code you just changed.
+

package/skills/debugging/references/runtimes/native-binary.md

@@ -0,0 +1,44 @@
+# Compiled binary without source
+
+When the failing component is a binary you cannot rebuild, the loop is unchanged — reproduce,
+observe, narrow — but every observation comes from outside the process.
+
+## Watch what it does, before opening it
+
+```bash
+strace -f -e trace=file,network ./binary        # Linux
+sudo dtruss -f ./binary                         # macOS
+ltrace ./binary                                 # library calls
+lsof -p <pid>                                   # what it currently holds open
+```
+
+Syscall tracing answers most questions — which config it actually read, which host it reached, where
+it failed — in one command, and costs nothing.
+
+## Then look inside
+
+```bash
+file ./binary && nm -C ./binary | head
+strings -n 8 ./binary | grep -i <term>
+objdump -d ./binary | less
+```
+
+`strings` finds error messages, paths, and version markers; matching the message you observed against
+the binary's string table locates the code path without a decompiler.
+
+## Crash
+
+```bash
+ulimit -c unlimited
+gdb --batch -ex bt ./binary core
+```
+
+A stripped binary yields addresses rather than names. Check for a separate debug package or a
+`.dSYM` before concluding the trace is useless.
+
+## Boundaries
+
+Confirm you are permitted to analyse and instrument the binary. Reverse engineering someone else's
+shipped software may be constrained by licence or contract; that is a real limit, not a formality,
+and it belongs in the report rather than being assumed away.
+

package/skills/debugging/references/runtimes/node.md

@@ -0,0 +1,43 @@
+# Node / TypeScript
+
+## Get the real stack
+
+```bash
+node --stack-trace-limit=50 app.js
+NODE_OPTIONS="--enable-source-maps" node dist/app.js
+```
+
+Without `--enable-source-maps` a TypeScript stack points into compiled output and the line numbers
+are a different file. Fix that before theorising about a frame.
+
+## Inspect a live process
+
+```bash
+node --inspect-brk app.js       # then attach; execution waits
+kill -USR1 <pid>                # open the inspector on an already-running process
+```
+
+## The failures that waste the most time
+
+- **Unhandled rejection swallows the trace.** `process.on("unhandledRejection", (e) => { throw e })`
+  during a hunt turns a silent exit into a real error.
+- **`async` frames are lost** unless the error was created in the async context. Create the `Error`
+  early and attach context, rather than reconstructing at the boundary.
+- **The file you edited is not the file that ran.** Stale `dist/`, a cached loader, or a package
+  resolving to `node_modules` rather than the workspace source. Print `import.meta.url` or
+  `require.resolve()` — do not assume.
+- **`NODE_ENV` and conditional exports** can select a different bundle entirely.
+
+## Cheap observations
+
+```bash
+node --trace-warnings app.js
+node --cpu-prof app.js          # for a hang or a slowdown
+node --heap-prof app.js
+```
+
+## Reproduce in isolation
+
+`npm exec -- node -e '<snippet>'` with the module imported directly is usually enough to separate a
+library defect from an integration defect. Do that before reading library source.
+

package/skills/debugging/references/runtimes/python.md

@@ -0,0 +1,41 @@
+# Python
+
+## Get the real traceback
+
+```bash
+python -X dev -X tracemalloc app.py
+python -m faulthandler app.py     # dumps a trace on a segfault or hang
+```
+
+`-X dev` enables development mode: extra warnings, unclosed-resource reporting, and a stricter
+allocator. It routinely surfaces the cause without any further work.
+
+## Inspect
+
+```bash
+python -m pdb -c continue app.py       # drops to pdb at the exception
+py-spy dump --pid <pid>                # stack of a live process, no restart
+py-spy top --pid <pid>                 # where time is actually going
+```
+
+`py-spy` needs no cooperation from the target and is the fastest way to diagnose a hang.
+
+## The failures that waste the most time
+
+- **The wrong interpreter.** `python`, `python3`, the venv, and the tool's vendored runtime are four
+  different environments. Print `sys.executable` and `sys.path` before believing an ImportError.
+- **Shadowing.** A local file named `queue.py` or `types.py` silently replaces the stdlib module.
+- **Mutable default arguments and class-level mutables** produce state that persists across calls in
+  a way that reads as impossible.
+- **`except Exception` upstream** is often why the error you see is not the error that happened.
+  Search for bare handlers before trusting the message.
+
+## Isolate
+
+```bash
+python -c 'import mod; print(mod.__file__); mod.thing()'
+```
+
+Import the module directly and call the failing function. Most "framework bug" reports do not
+survive this.
+

package/skills/debugging/references/runtimes/rust.md

@@ -0,0 +1,37 @@
+# Rust
+
+## Get the real failure
+
+```bash
+RUST_BACKTRACE=full cargo run
+cargo test -- --nocapture --test-threads=1
+```
+
+`--nocapture` matters: without it, `println!` from a passing-then-failing test is hidden, which is
+usually where the evidence was.
+
+## Sanitizers and Miri
+
+```bash
+cargo +nightly miri test                       # undefined behavior in unsafe code
+RUSTFLAGS="-Zsanitizer=address" cargo +nightly test --target <host-triple>
+cargo test -- --test-threads=1                 # order-dependent state
+```
+
+For anything involving `unsafe`, Miri is the first move, not the last. It catches aliasing and
+provenance violations that produce correct-looking behavior in debug and corruption in release.
+
+## The failures that waste the most time
+
+- **Debug and release differ.** Integer overflow panics in debug and wraps in release. A bug that
+  only appears in `--release` is often this, or a UB issue the optimiser exposed.
+- **`unwrap()` on a `Result` reports the panic site, not the origin.** Use `anyhow::Context` or
+  `expect("what was being attempted")` so the message names the operation.
+- **Trait resolution surprises:** a blanket impl or a deref chain selecting a different method than
+  the one read. `cargo expand` shows what was actually generated.
+
+## Isolate
+
+`cargo test -p <crate> --lib <module>::` narrows to one module. If the failure disappears, the cause
+is in the integration, not the unit.
+

package/skills/debugging/references/tools.md

@@ -0,0 +1,72 @@
+# Specialist tools
+
+Reach for these only when ordinary instrumentation genuinely cannot see the failure. Each one is
+heavier than it looks, and each one changes the user's machine or attaches to a live process — that
+needs the same approval as any other change.
+
+## Native debuggers — `gdb` / `lldb`
+
+For a crash, a hang, or corruption in compiled code. The highest-value use is not stepping; it is a
+backtrace from a core file, which costs one command and often ends the hunt.
+
+```bash
+ulimit -c unlimited          # allow core dumps in this shell
+gdb --batch -ex bt -ex 'info registers' ./binary core
+lldb --batch -o 'bt all' -o 'register read' -f ./binary -c core
+```
+
+Build with `-g` and without `-O2` before concluding a backtrace is unreadable. Optimised frames are
+inlined away and the resulting trace is not evidence of anything.
+
+`pwndbg` and `gef` are `gdb` plugins that add heap and register views. They are worth installing for
+memory-corruption work and pointless otherwise.
+
+## Sanitizers — cheaper than a debugger
+
+For C, C++, Rust, and Go, a sanitizer run usually finds the cause faster than any interactive
+session, because it reports at the moment of the violation rather than at the crash.
+
+```bash
+clang -fsanitize=address,undefined -g -O1 prog.c && ./a.out
+go test -race ./...
+RUSTFLAGS="-Zsanitizer=address" cargo +nightly test    # or: cargo miri test
+```
+
+Run these before attaching a debugger. A clean sanitizer run is also real evidence.
+
+## Static binary analysis — `ghidra`, `objdump`, `nm`
+
+Only when source is unavailable. Start with the cheap tools: `nm -C`, `strings`, `objdump -d`, and
+`ltrace`/`strace` (`dtruss` on macOS) will answer most questions about what a binary calls and when.
+Ghidra's decompiler is for the cases those cannot reach; it is a large install and a long session.
+
+Confirm you are permitted to analyse the binary before starting.
+
+## Protocol and exploit work — `pwntools`
+
+For byte-exact interaction with a process or socket when a shell cannot express it.
+
+```python
+from pwn import process, remote
+io = process("./binary")          # or: remote(host, port)
+io.sendline(b"payload")
+print(io.recvall(timeout=2))
+```
+
+The library is authorization-sensitive by nature. Use it against systems you own or are engaged to
+test, and say which applies.
+
+## Browser failures — Playwright CLI
+
+For a symptom only reproducible in a real page. The tracing mode is what makes it worth the setup:
+it captures network, console, and DOM snapshots together, which is exactly the correlation a
+screenshot loses.
+
+```bash
+npx playwright open --save-trace=trace.zip https://example.test
+npx playwright show-trace trace.zip
+```
+
+Console output alone is not reproduction. A trace that shows the failing request next to the failing
+render is.
+