sbcl-usage

name	sbcl-usage
description	Practical SBCL (Steel Bank Common Lisp) operations guide. Use this skill whenever the user mentions SBCL execution/debugging, --script usage, REPL workflows, backtraces, ASDF loading, save-lisp-and-die, profiling, or SLY-based Common Lisp development.
version	1.0.0

Provide end-to-end operational guidance for SBCL: running programs, debugging failures, profiling performance, and producing executables. This complements common-lisp-ecosystem by focusing on practical runtime workflows. Read - Inspect Lisp/ASDF files, configs, logs Edit - Update *.lisp / *.asd / run scripts Bash - Execute sbcl / roswell / qlot / nix commands mcp__context7__get-library-docs - Verify SBCL / ASDF / CFFI details SBCL invocation mode selection (REPL / script / non-interactive) Debugger-centric root cause analysis (backtrace, restarts, inspect, trace) ASDF, Quicklisp, Roswell, and Qlot execution workflows Performance measurement (time, sb-profile, sb-sprof) Executable generation with save-lisp-and-die SBCL usage in Nix-based environments Full API tutorials for every external library (use Context7 when needed) General language architecture topics already covered by common-lisp-ecosystem

<sbcl_cli> Primary SBCL startup modes and when to use each

Interactive exploration and iterative debugging sbcl sbcl --noinform Reproduce the failure in REPL first, then minimize the input. Use --noinform when you want less startup noise. Batch jobs, automation, CI execution sbcl --script tools/task.lisp Design explicit exit codes for operational reliability. Wrap top-level failures with handler-case + sb-ext:exit. One-liner load-and-run flows in CI or local automation sbcl --non-interactive \ --eval '(require :asdf)' \ --eval '(asdf:load-system :my-app)' \ --eval '(my-app:main)' Prefer --non-interactive in CI to avoid hanging on prompts. Move complex startup logic to --script for maintainability. Custom core image workflows or strict startup control sbcl --core my.core sbcl --disable-debugger --non-interactive --eval '(...)' Do not disable debugger during root-cause investigation. Use custom core images sparingly to preserve reproducibility.

<asdf_workflow> ASDF-centered loading and execution patterns

(require :asdf) (asdf:load-system :my-app) Validate load-system success before deeper debugging. Read the first ASDF failure carefully; avoid chasing secondary errors. sbcl --non-interactive \ --eval '(require :asdf)' \ --eval '(asdf:test-system :my-app/test)' Keep a one-line reproducible test command for team sharing. Prefer Qlot for dependency reproducibility qlot install qlot exec sbcl --non-interactive --eval '(require :asdf)' --eval '(asdf:load-system :my-app)' Use pinned dependency sets to reduce local-vs-CI drift.

<debugging_workflow> High-efficiency SBCL debugging flow for fast root-cause discovery

Produce a stable minimal reproduction Fix the execution mode first (REPL or script) Stable execution mode selected Strip inputs/environment to a minimal failing case Minimal reproducible failure case Observe failure location, not only symptom text Inspect debugger backtrace and stack frames Candidate fault location identified Use inspect/describe for problematic objects Object state diagnostics captured Use trace for high-value call-path visibility Call-path evidence captured (trace my-app::parse-input) (untrace my-app::parse-input) (describe some-object) (inspect some-object) Test one root-cause hypothesis at a time Define observable signals per hypothesis Hypothesis-to-signal mapping Use step/break/log checks to prove or reject each signal Validated or rejected hypotheses Apply minimal fix and verify non-regression Re-run the same reproduction command after the fix Fix effectiveness verified Add tests that preserve the failure case Regression protection added Use restart flows to keep diagnosing while preserving continuity (restart-case (dangerous-op x) (use-default () :report "fallback value" 0) (retry () :report "retry operation" (dangerous-op x))) Explicit recovery paths let you observe failures and continue operation without blindly swallowing diagnostics. Minimum interactive debugger controls to master Backtrace and frame navigation Local variable inspection Restart selection (abort/retry/use-value) Explicit invoke-debugger usage when needed

<performance_profiling> Standard SBCL performance workflow

(time (my-app:run-once input)) Start with time before introducing complex profiling. (require :sb-profile) (sb-profile:profile my-app::hot-fn my-app::other-hot-fn) (my-app:run-benchmark) (sb-profile:report) (sb-profile:unprofile) Identify hot functions at call-site granularity. (require :sb-sprof) (sb-sprof:with-profiling (:max-samples 3000 :report :flat) (my-app:run-benchmark)) Use when you need lower overhead and broad execution trends. Apply optimization declarations locally and verify impact (declaim (optimize (speed 3) (safety 1) (debug 1))) (defun hot (x y) (declare (type fixnum x y)) (+ x y)) Avoid safety 0 unless you have hard evidence and strong tests.

<build_and_release> Executable image generation baseline

(defun main () (handler-case (progn (my-app:run) (sb-ext:exit :code 0)) (error (e) (format *error-output* "fatal: ~a~%" e) (sb-ext:exit :code 1))))

  (sb-ext:save-lisp-and-die "my-app"
    :toplevel #'main
    :executable t
    :compression t)
</example>
<notes>
  <item>Always define explicit process exit codes.</item>
  <item>Validate ASDF load and tests before image generation.</item>
</notes>

<ecosystem_integration> In this environment, prefer SLY over SLIME Assume sly / sly-asdf / sly-macrostep workflows for Emacs integration. When explaining editor actions, provide SLY-compatible guidance.

Reproducible SBCL execution in Nix environments nix shell nixpkgs#sbcl sbcl --version Pin project environments via shell.nix or flake.nix when needed. Combine with Qlot for stronger dependency reproducibility. Simplify implementation management and script execution ros install sbcl ros run ros build app.ros

<decision_tree name="execution_mode_selection"> Which run mode should be selected? REPL mode (sbcl / --noinform) --non-interactive + --eval/--script save-lisp-and-die executable flow Qlot + Nix (and Roswell when useful) </decision_tree>

<best_practices> Do not use --disable-debugger during root-cause analysis; capture backtraces first. Keep one reproducible command line for before/after fix verification. Use trace/inspect/describe to convert assumptions into observable evidence. Require measurement (time/sb-profile/sb-sprof) before performance changes. Adopt Qlot for projects that need deterministic dependency state. Design batch jobs with explicit success/failure exit codes. Avoid SLIME-only advice in SLY-based environments. </best_practices>

<anti_patterns> Disabling debugger before diagnosis removes critical evidence. Use interactive debugger state first (frames, restarts, object inspection).

Applying optimization declarations without evidence. Measure hotspots first; optimize only proven bottlenecks. Swallowing errors with handler-case and hiding root cause. Preserve diagnostic visibility with logging/rethrow/restart strategies. Allowing per-machine dependency drift. Use Qlot (and Nix when appropriate) to lock execution context. Prioritize observability (backtrace, inspect, trace) during root-cause analysis. Fix proposals must include reproduction, verification, and failure-mode behavior. Performance recommendations must be grounded in measured data. Confirm ASDF load viability before diving into deeper implementation details. Select execution mode explicitly from task constraints. Use save-lisp-and-die with explicit exit-code policy for operational binaries. Reproduce and record the failure 1. Choose run mode (REPL / script / non-interactive) Workflow guidance Step completed 2. Build a minimal reproduction Workflow guidance Step completed 3. Capture backtrace and input conditions Workflow guidance Step completed Narrow and validate root-cause hypotheses 1. Observe state with inspect / describe / trace Workflow guidance Step completed 2. Define recovery paths using restarts Workflow guidance Step completed 3. Test one hypothesis at a time Workflow guidance Step completed Confirm fix quality and regression safety 1. Re-run the exact reproduction command Workflow guidance Step completed 2. Run asdf:test-system Workflow guidance Step completed 3. Profile if performance side effects are possible Workflow guidance Step completed Debugging guidance must preserve the sequence: reproduce → observe → verify Keep SLY compatibility in editor integration guidance Provide Nix/Qlot reproducibility guidance when environment drift is likely Unmeasured optimization Layering workaround code without identifying root cause

<related_skills> CLOS/ASDF/condition-system foundations Pinned SBCL runtime environments with nix shell/flake Evidence-driven root-cause methodology Automated checks and CI quality discipline </related_skills>