What does lisper do?
Operating Rule
Use this skill as a set of assertions. Treat each assertion as satisfied, violated, or explicitly deferred by a user constraint. Prefer exact code facts over taste claims. Name the package, symbol, struct, condition, macro expansion, invariant, test, or side-effect boundary that makes the assertion true.
State the fact. Name the witness. Do not argue taste.
When reporting about Common Lisp or Emacs Lisp code, write in short declarative statements:
- The invariant is in the constructor.
- The dynamic extent is bounded by
unwind-protect. - The macro leaks evaluation order.
- The condition is structured.
- The destructive list op mutates caller structure.
- The predicate is naked.
- The compiler warning remains.
- The buffer effect leaks into the pure core.
Assertions
-
Code pictures a model. S-expressions are syntax trees before they are text. Preserve every real state of the problem. Use symbols, tagged structures (
defstruct/cl-defstruct), CLOS classes, or algebraic alists/plists with explicit constructors. Erase only distinctions that are not semantically used. -
Higher-order functions compose before macros rewrite. Lisp is lambda calculus first: functions are first-class values, closures carry lexical environments, and currying (
apply-partiallyor returning(lambda (x) ...)) replaces multi-parameter plumbing. When the same structure appears twice, inspect it; when it appears three times, abstract it with a higher-order combinator, curried closure, or generic function—never a 10-argument procedural helper. Introduce a macro only to control evaluation, bind lexical symbols, or eliminate compile-time boilerplate. Every macro must evaluate value arguments at most once in left-to-right order and bind temporaries withgensym/make-symbol(with-gensyms). -
Pure data transforms stay outside the image's mutable world. Prefer catamorphisms (
cl-reduce/seq-reduce), homomorphic mappings (mapcar/seq-keep), and predicate pipelines (seq-filter) over imperativelet+setq+push+nreverseloops. Separate pure symbolic/list/structure transformations from buffer mutation, process IO, filesystem state, network streams, timers, and global specials (*earmuffs*). Core functions take values and return values. Host effects stay in named boundary functions. -
Lexical scope is the default law. Every Emacs Lisp file must begin with
;; -*- lexical-binding: t; -*-on line 1. Every dynamic special variable in Common Lisp or Emacs Lisp must wear*earmuffs*(or+plus-signs+for constants in CL) and be rebound dynamically withletrather than mutated globally withsetq/setf, unless changing global configuration is the explicit contract. -
Invariants are propositions. Express invariants in types (
deftypewithsatisfies,ftypeproclamations,defstruct:typeslots) first, smart constructors (:constructor) second, runtime assertions (check-type/cl-check-type) third, tests fourth, and comments last. A constructor is a proof that a structure satisfies its slot invariants. -
Conditions are algebraic facts, not raw strings. Define explicit condition hierarchies (
define-conditionin Common Lisp;define-errorin Emacs Lisp). Signal structured conditions witherror/cerror/signalso callers can handle them withhandler-case,handler-bind, orcondition-casewithout matching error message substrings. Use Common Lisp restarts (restart-case) when recovery policy belongs to the caller and mechanism belongs to the low-level function. -
Cons-cell ownership is a semantic claim. Treat input lists, trees, and sequences as immutable unless the function's name and docstring explicitly declare destructive behavior (
nreverse,nconc,delete,sort,cl-delete,setfon shared cons cells). Never apply destructive operations to quoted literals ('(a b c)) or borrowed caller lists. Duplicate structure (copy-list,copy-tree,copy-sequence) only at the boundary where mutation begins. -
Quality is witnessed, not asserted. Zero byte-compiler warnings, zero
checkdoc/package-linterrors, and zero SBCLSTYLE-WARNINGdiagnostics are only the floor. Add ERT (ert-deftest) or FiveAM/Rove/Parachute tests for pure transformations, macro-expansion laws, boundary inputs, dynamic cleanup under non-local exit, and fixed regressions. A test name states the proposition it witnesses. -
Documentation and namespace prefixes are part of the public contract.
- In Common Lisp: define explicit packages (
defpackage/uiop:define-package) without wholesale:usepollution beyond:cl; document every exported function, macro, class, variable, and condition. - In Emacs Lisp: prefix every public symbol with
<package>-and every internal symbol with<package>--; writecheckdoc-compliant docstrings whose first line is a complete sentence and whose parameter references areUPPERCASE; declarePackage-Requiresand;;; Commentary:headers accurately.
- In Common Lisp: define explicit packages (
-
Resource lifetime is bounded by dynamic extent. Never pair manual allocation and cleanup across fallible expressions. Wrap every temporary buffer change, point movement, file handle, process, socket, or hook installation in
unwind-protect(orwith-open-file,with-temp-buffer,save-excursion,save-restriction,save-match-data). Non-local exits (throw,return-from,signal,error) must leave global state and buffers clean. -
Size and parenthesis layout are structural signals. Keep each source file under 1000 lines and each
defun/defmacroexecutable body (excluding its docstring anddeclareforms) under 80 lines. Never truncate docstrings, delete explanatory comments, or pack multiple sequential side-effecting forms onto a single line to game line-count limits. Never place closing parentheses)))alone on trailing lines. Indent according to standard Lisp form semantics (declaring(declare (indent ...))on every Elisp macro). Split files and functions by domain proposition, not by arbitrary line-count slices or vagueutilsbuckets. -
Logic deserves a name. Do not expose raw
car/cdr/nthchains (cadddr), nestedassoc/plist-getplumbing, or multi-clauseand/or/notexpressions at the call site when they express a domain proposition. Define named accessors and semantic predicates ending in-porp(e.g.,order-matchable-p,same-principal-p,session-active-p).
Model Completeness
Before choosing packages, structs, and functions, name the formal model that makes the code coherent.
For macros and syntactic transformations:
- A macro is a compiler pass from syntax to syntax: $\text{AST}{\text{surface}} \to \text{AST}{\text{core}}$.
- Specify the surface grammar (destructuring lambda list), the binding discipline, the evaluation multiplicity of every subform, and the target expansion.
- Verify hygiene with
macroexpand-1/macrostep: no free symbol capture, no multiple evaluation of effectful arguments, and no runtimeeval. - If a macro expands into definitions, preserve source locations and declarations (
declare, docstring placement) for the host compiler and inspector.
For interactive state, buffers, and concurrent processes:
- An interactive system is a state transition relation before it is a buffer or thread.
- Separate the domain state value from the rendering buffer (Emacs UI) or worker thread/socket (CL/Emacs process).
- Model asynchronous process output (Emacs process filters/sentinels, CL threads/channels) as discrete events feeding a total state transition: $\text{State} \times \text{Event} \to (\text{State} \times \text{List}[\text{Effect}])$.
- Process filters in Emacs Lisp may receive arbitrary chunk boundaries; buffer and parse incomplete frames explicitly before dispatching domain events.
- Guard buffer-local state (
defvar-local) against killed buffers (buffer-live-p) when timers, sentinels, or callbacks fire asynchronously.
For conditions, restarts, and non-local control:
- Separate what went wrong (the condition datum) from how to recover (restarts in CL; structured handlers in Elisp) and which recovery to choose (the outer policy handler).
- Never swallow conditions with a bare
(ignore-errors ...)or(condition-case nil ... (error nil))unless the exact ignored condition type is narrowed and the fallback value is a valid domain state.
Formal Logic Comments
Use formal comments only when they clarify a proof obligation that ftype, deftype, or cl-defstruct does not fully express. Use ;; inside functions/forms and ;;; at top level, following standard Lisp comment hierarchy (;;;; section, ;;; top-level, ;; aligned in-body, ; margin).
;;; Pre: (and ( <= 0 start end (length sequence)) (listp sequence))
;;; Post: (and (equal result (subseq sequence start end))
;;; (not (eq result sequence)))
(defun slice-copy-checked (sequence start end)
"Return a fresh subsequence of SEQUENCE from START to END."
(check-type sequence list)
(assert (<= 0 start end (length sequence)))
(copy-list (subseq sequence start end)))
;;; Invariant: (null (intersection (work-set-pending ws) (work-set-completed ws) :test #'equal))
;;; Preservation: `work-set-complete' removes ID from `pending' before consing onto `completed'.
(defstruct (work-set (:copier nil))
(pending nil :type list)
(completed nil :type list))
;;; Law: (equal (decode-packet (encode-packet x)) x) for all valid packet structs X.
Prefer these forms:
Pre: the condition a caller must satisfy.Post: the condition the function guarantees, including freshness/sharing (eqvsequal).Invariant: the proposition preserved across struct/buffer/session operations.Law: an algebraic or macro-expansion relation that tests must witness.Preservation: why a transition orunwind-protectform keeps the invariant true.
Semantic Predicates
Use named predicates following Lisp -p / p conventions to express domain logic declaratively:
- Single-word root (Common Lisp convention):
evenp,Orderp->orderp,validp(or in Elisp,-pconsistently for package-prefixed symbols). - Hyphenated root (both CL and Elisp):
order-matchable-p,same-principal-p,lispm-session-live-p.
Prefer:
(when (order-matchable-p order resting-order)
(match-order book order resting-order))
(when (same-principal-p actor owner)
(grant-access actor resource))
Avoid:
(when (and (not (eq (order-side order) (order-side resting-order)))
(>= (order-price order) (order-price resting-order))
(plusp (order-quantity order)))
(match-order book order resting-order))
(when (and (equal (principal-id actor) (principal-id owner))
(eq (principal-realm actor) (principal-realm owner)))
(grant-access actor resource))
Also avoid deep positional list access ((cadddr record), (nth 4 item)) in domain logic; define a defstruct / cl-defstruct or named accessor functions so the call site reads the domain concept rather than the cons topology.
Implementation Discipline
Start from the domain and respect the dialect's functional semantics.
- Currying, Partial Application, and Combinators:
- Never decompose a long function by extracting a procedural helper with 6+ positional parameters that mirror the caller's
let*bindings, or by slicing alet*into single-usefoo--part-1/foo--part-2subroutines. - Never introduce "fake currying" (e.g.,
(lambda (getter-fn) (lambda () ...))) to simulate a lexical scope that a locallet*already provides. - Instead, curry genuine domain invariants into lexical closures (
(defun domain--matcher (query role) (lambda (event) ...))or(apply-partially #'fn fixed-arg)) and compose small unary/binary transformations: $f \circ g = \lambda x., f(g(x))$. - Replace repetitive imperative polling, cycle-safe graph traversal, or resource-bracket patterns with higher-order combinators that accept a step function
(funcall step item)and return values.
- Never decompose a long function by extracting a procedural helper with 6+ positional parameters that mirror the caller's
- Equality precision: Never use
eqwhereeql(numbers/characters),equal(structural strings/lists), orequalp/ domain equality is required. Choose the tightest equality predicate that matches the type's equivalence relation, and pass:test #'equalexplicitly toassoc,member,gethash,remove, andcl-findwhen keys are strings or composite values. - Emacs Lisp specifics:
- Line 1 must declare
;; -*- lexical-binding: t; -*-. - Use
cl-lib(cl-defstruct,cl-loop,cl-destructuring-bind,cl-check-type), never the deprecated runtimeclpackage. - Guard all point, mark, narrowing, and match-data side effects with
save-excursion,save-restriction, andsave-match-data. - Prefer buffer-passing or explicit
(with-current-buffer buf ...)over assumingcurrent-bufferacross asynchronous boundaries. - Annotate macros with
(declare (indent ...) (debug ...))so indentation and Edebug instrumentation work automatically.
- Line 1 must declare
- Common Lisp specifics:
- Proclaim
(declaim (ftype (function (...) ...) name))for public domain functions so SBCL performs compile-time type inference and exhaustiveness checks. - Use
etypecase/ecase/ctypecaseinstead of open-endedcase/typecaseso unhandled variants signal a structured type error immediately. - Avoid reader-table pollution and unexported symbol leaks (
pkg::internal-sym). - Prefer ASDF package-inferred or explicit serial
:componentswith clean dependency DAGs.
- Proclaim
- Forbidden constructs in production paths:
- No runtime
evalto dispatch functions or construct code (usefuncall,apply, or compile-time macros). - No dynamic
setqon undeclared free variables. - No in-place mutation (
nconc,nreverse,delete,sort) of quoted literals or unowned caller lists. - No bare
(ignore-errors ...)hiding unexpected program bugs. - No dangling closing parentheses on their own lines.
- No runtime
Review Protocol
When reviewing, writing, or refactoring Lisp code under this skill, run the verification tools appropriate to the dialect before claiming compliance. Always enforce an explicit command timeout.
Emacs Lisp Verification Floor
# 1. Strict Byte-Compilation (warnings treated as errors) in clean Emacs
/opt/homebrew/bin/timeout 30 emacs -Q --batch \
-L . \
--eval "(setq byte-compile-error-on-warn t)" \
-f batch-byte-compile <files.el>
# 2. Checkdoc & Package-Lint (when available or via Eask/Eldev)
/opt/homebrew/bin/timeout 30 emacs -Q --batch \
--eval "(require 'checkdoc)" \
--eval "(dolist (f command-line-args-left) (checkdoc-file f))" <files.el>
# 3. ERT Batch Test Suite
/opt/homebrew/bin/timeout 30 emacs -Q --batch \
-L . -L test \
-l <test-file.el> \
-f ert-run-tests-batch-and-exit
Common Lisp Verification Floor
# 1. Strict SBCL Compilation (fail on any WARNING or STYLE-WARNING)
/opt/homebrew/bin/timeout 60 sbcl --noinform --non-interactive \
--eval '(require :asdf)' \
--eval '(handler-bind ((warning (lambda (c) (uiop:die 1 "Compiler warning: ~A" c))))
(asdf:compile-system :<system-name> :force t))'
# 2. sblint / lisp-critic (if installed in environment)
/opt/homebrew/bin/timeout 60 sblint <system.asd>
# 3. ASDF Test Suite
/opt/homebrew/bin/timeout 60 sbcl --noinform --non-interactive \
--eval '(require :asdf)' \
--eval '(asdf:test-system :<system-name>)'
Check structure:
- Every
.elfile haslexical-binding: ton line 1, valid package headers, andprovideat the bottom. - Every
.lispfile begins with(in-package #:...)and belongs to an explicit ASDF component. - Compiler output has zero
WARNINGand zeroSTYLE-WARNINGdiagnostics. - Public symbols have contract-focused docstrings (
checkdoc-clean in Elisp). - Conditions use
define-condition(CL) ordefine-error(Elisp), not ad-hoc strings. - Macros are hygienic (
gensym), single-evaluating, and necessary. - Destructive sequence operations never mutate shared or literal structure.
- Equality predicates (
eq,eql,equal) and hash/list:testarguments match key types. - Dynamic state, buffers, files, and processes are protected by
unwind-protectorwith-*macros. - Domain propositions are expressed as
-p/psemantic predicates instead of naked boolean/cons plumbing. - Closing parentheses are stacked on the final expression line, never dangling on separate lines.
- No source file exceeds 1000 lines; no
defun/defmacroexceeds 80 lines.
Response Pattern
When applying the skill, report findings as assertions:
The file header omits lexical-binding: t in parser.el.
The macro with-retry evaluates the form argument twice without gensym.
The destructive sort in rank-candidates mutates the caller's list in place.
The assoc lookup on string keys omits :test #'equal.
The buffer excursion in render-view lacks save-excursion and unwind-protect.
The error in decode-frame signals an untyped string instead of a defined condition.
The cadddr chain in extract-header exposes tuple position instead of a struct accessor.
The conditional in can-dispatch-p is naked at the call site.
If a user asks for implementation, fix the violation directly. If a user asks only for review, stay read-only and list violations with file and line references.