<version_info> <current_version>SBCL 2.5.x (2026 stable)</current_version> All patterns in this skill apply to SBCL 2.x series. SBCL releases frequently (monthly builds); use nix or Roswell to pin a specific version. </version_info>
<sbcl_cli> Primary SBCL startup modes and when to use each
<asdf_workflow> ASDF-centered loading and execution patterns
<debugging_workflow> High-efficiency SBCL debugging flow for fast root-cause discovery
<compile_load_hang_triage> A distinct class of failures where SBCL stops making progress (no error, no backtrace, no output) inside compile-file, load, or asdf:load-system rather than signalling. These are compile-unit and load-order phenomena, not ordinary runtime bugs: the same forms frequently compile and load fine in isolation but stall when combined in one file or one image. Diagnose them structurally, and prefer decomposition over per-form workarounds.
<general_principle name="shrink_the_compile_unit"> Treat the compile unit (the file handed to compile-file, or a single ASDF component) as the primary variable. Splitting a stalling file into smaller source files loaded serially is the durable fix; per-form workarounds are stopgaps. Many stalls arise from compile-time interaction between top-level forms in the same unit — macro-generation feeding later macro invocations, large constant folding, or definition ordering — not from any single form. Reducing the unit removes the interaction. </general_principle>
<general_principle name="keep_top_level_forms_boring"> Define top-level helpers with plain defun rather than a top-level (setf (symbol-function 'name) (lambda ...)) or an eager (compile nil (lambda ...)) at registration time. Keep constant-heavy work inside runtime helper functions instead of thin top-level wrappers that invite constant folding of large literals. Top-level symbol-function assignment of a full lambda body, and thin wrappers that return a large constant vector/list, have been observed to trigger compile/eval stalls where the equivalent plain defun (or a non-constant construction path) loads normally. Specific triggers observed on SBCL 2.6.0 (macOS/Nix); the general guidance — keep top-level forms simple and side-effect-light — is dialect-stable. ;; risky at top level: symbol-function assignment of a full lambda body (setf (symbol-function '%encode) (lambda (s) #| large body |#)) ;; safe: plain defun (defun %encode (s) #| large body |#)
;; risky: a thin wrapper that folds a large constant vector at compile time
(defun tokens () #(#| hundreds of literal specs |#))
;; safe: build the vector at runtime through a non-constant argument path
(defun tokens (specs) (build-token-vector specs))
;; drop unneeded generated copiers that enlarge a defstruct-heavy compile unit
(defstruct (node (:copier nil)) a b c)
</example>
</general_principle>
<general_principle name="watch_macro_expansion_size"> A macro whose expansion grows combinatorially with its arguments can make macroexpand/compile appear hung. Emit a linear runtime construction instead of enumerating a branch per argument subset, and add a macroexpansion-size regression test for high-arity call sites. Observed case: a keyword-wrapper macro emitting one direct-call branch per &key presence subset produced on the order of 2^N branches for N keys, so a wrapper with ~18 keys generated hundreds of thousands of branches. The load stall was macroexpansion blow-up, not the wrapped function. </general_principle>
<general_principle name="load_order_is_a_variable"> A file that compiles alone can stall when compiled after another file has been loaded into the same image. When a stall appears only in-sequence, suspect load-order/compile-unit interaction and re-verify each unit in a fresh image. Observed with definition-heavy files (e.g. a run of many defstruct forms) that compiled in a fresh image but stalled once an earlier file had been loaded first — evidence the trigger is cross-unit state, not the file's own source. </general_principle>
<observed_triggers> Version-scoped field observations (SBCL 2.6.0), recorded as reproduction conditions rather than universal rules. Use them as hypotheses to test, not guarantees, and re-validate before relying on any workaround. A run of many top-level defstruct forms in one compile unit; adding one more struct crosses a threshold and compile-file stalls. Mitigations: split structs across serially-loaded files; add (:copier nil) to drop unneeded generated copiers. A thin top-level wrapper returning a large constant vector/list, folded at compile time. Mitigation: build the vector inside a runtime helper or pass the specs through a non-constant argument path. Top-level (setf (symbol-function 'name) (lambda ...)) with a substantial body. Mitigation: plain defun. Predicates branching on implementation Unicode category/width tables via member/case under a bootstrap-loaded image. Mitigation observed: bind the return value and compare with explicit eq/or checks. Forcing sb-ext:evaluator-mode to :interpret across a whole file to dodge a compile stall — frequently just relocates the stall to a later file or to execution time. Treat evaluator-mode guards as a dead end for a durable fix unless paired with a structural decomposition and fresh verification. </observed_triggers> </compile_load_hang_triage>
<headless_verification_harness> A sound, non-interactive harness is a prerequisite for diagnosing the stalls above: if the timeout mechanism is unsound, a stalled form and a stalled harness are indistinguishable, producing false positives. Build the harness correctly before trusting any hang observation.
<form_bisect_and_package_preflight> Techniques for pinning the exact offending form once a stall is confirmed, and for keeping the reproducer itself from manufacturing false failures.
<coverage_measurement_bias> sb-cover reports low expression coverage for files dominated by top-level defining forms and metadata side effects (defpackage, define-condition, top-level documentation/table assignments), even when the runtime contracts they establish are fully tested. These forms are counted as expressions but are not all attributed as executed by ordinary test runs. <how_to_apply>Separate genuine runtime gaps from instrumentation bias by comparing a low-coverage file against its shape: definition-heavy files may warrant a few explicit contract tests but need not reach 100%; logic-heavy files are the higher-value targets for additional tests or refactoring. Do not distort public API design solely to satisfy sb-cover on top-level metadata; prefer explicit tests plus a documented exception.</how_to_apply> sb-cover does not clean its own HTML output directory; after splitting or renaming source files, clear the stale report before reading a new one. </coverage_measurement_bias>
<performance_profiling> Standard SBCL performance workflow
<build_and_release> Executable image generation baseline
(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.
<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. Verify every hang observation with a sound fork/wait timeout; an exec-after-alarm wrapper never fires and fabricates false stalls. Decompose a stalling compile unit into smaller serially-loaded files rather than reaching for per-form workarounds or whole-file evaluator-mode guards. Bisect compile/load stalls by complete top-level forms, never by line ranges; use a read/eval form-trace to name the offending form. Run verification one unit per fresh SBCL process (--no-sysinit --no-userinit --disable-debugger) with an isolated FASL cache. </best_practices>
<anti_patterns> Disabling debugger before diagnosis removes critical evidence. Use interactive debugger state first (frames, restarts, object inspection).
<error_escalation inherits="core-patterns#error_escalation"> Minor SBCL warning during compilation Unhandled condition or ASDF load failure Runtime error or heap exhaustion in production image Memory corruption or undefined behavior in FFI boundary </error_escalation>
<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> <related_agents> Locate code patterns and references in this skill domain Review implementation quality against this skill guidance Analyze code complexity and suggest refactoring improvements </related_agents>