Skip to content

luthersystems/elps / .claude/skills/implement

implement

Verified

/implement — Code Change Skill

Implements any code change in the ELPS codebase. This is the foundation skill — all other skills reference its patterns.

Trigger

Use when asked to implement a feature, fix a bug, add a builtin, modify the parser, update the formatter, add CLI flags, update docs, or make any other code change.

Workflow

1. Classify the Change

Determine the change type to know which files to touch:

TypePrimary FilesTest Pattern
builtinlisp/builtins.go (langBuiltins)elpstest.TestSuite in a topical lisp/*_test.go (e.g. math_test.go)
special-oplisp/op.go (langSpecialOps)elpstest.TestSuite in a topical lisp/*_test.go
macrolisp/macro.go (langMacros)elpstest.TestSuite in lisp/macro_test.go or a topical file
linterlint/analyzers.go, lint/lint.golint/lint_test.go (use /add-linter-check skill)
elpsvetcmd/elpsvet/go test ./cmd/elpsvet/ (use /elpsvet skill)
fuzz<pkg>/fuzz_test.go, internal/fuzzseed/make fuzz (use /fuzz skill)
stdliblisp/lisplib/lib<name>/elpstest.Runner + .lisp test file (use /add-stdlib-package skill)
clicmd/<command>.goManual verification or integration tests
formatterformatter/formatter.goformatter/formatter_test.go (TestASTPreservation, TestRepoFileRoundTrip)
parserparser/rdparser/parser.go, parser/lexer/parser/rdparser/parser_test.go
diagnosticdiagnostic/diagnostic.go, diagnostic/renderer.godiagnostic/renderer_test.go
bug-fixVaries — find the root cause firstRegression test reproducing the bug
docsdocs/lang.md (embedded), docs/templates.md, docs/embed.md, docs/minify.md, docs/lint-checks.md, AGENTS.md, skills./elps doc --guide to verify rendering of embedded guides
depsgo.mod, go.summake test to verify compatibility
ci.github/workflows/*.ymlPush and verify Actions run
profilerlisp/x/profiler/Profiler-specific tests

2. Read Before Writing

Where to find the existing patterns for each kind of change:

  • For builtins: read nearby entries in langBuiltins (lisp/builtins.go) and their builtinXxx functions
  • For ops: read langSpecialOps in lisp/op.go for the opXxx naming convention
  • For macros: read langMacros in lisp/macro.go for the macroXxx patterns
  • For linter: read existing analyzers in lint/analyzers.go
  • For stdlib: read an existing package like lisp/lisplib/libmath/

3. Implement

Follow these rules for all ELPS code:

Go Implementation Rules

  • Function signature: func builtinXxx(env *lisp.LEnv, args *lisp.LVal) *lisp.LVal
  • Formals: Formals("a", "b"); modifiers are plain symbols — Formals("a", OptArgSymbol, "b") (&optional), VarArgSymbol (&rest), KeyArgSymbol (&key). Formals are untyped: check args.Cells[i].Type in the body and return env.Errorf(...) on a mismatch
  • Error propagation: Return env.Error("message") or env.Errorf("format", args...). Errors are *LVal values with Type == LError, NOT Go error interface
  • Check errors: After any call that returns *LVal, check if v.Type == lisp.LError { return v } to propagate
  • Docstrings are mandatory: CI runs elps doc -m and fails if any builtin/op/macro lacks a docstring
  • Registration: Add a {"name", Formals(...), fn, docstring} entry to langBuiltins, langSpecialOps, or langMacros (returned by DefaultBuiltins() / DefaultSpecialOps() / DefaultMacros())

Lisp Code Rules

  • set creates bindings. set! mutates existing bindings. First binding MUST use set
  • No backtick reader syntax — write (quasiquote ...) / (unquote ...)
  • true and false are symbols, not special forms
  • () is nil/falsey, everything else is truthy
  • Keywords start with : (e.g., :key-name)
  • Qualified symbols use : separator (e.g., math:pi)

Adding a builtin, special operator, or macro

  1. Implement it in lisp/builtins.go, lisp/op.go, or lisp/macro.go.
  2. Give it a docstring in the definition — CI runs elps doc -m.
  3. If the form has structural requirements (e.g. rethrow only inside handler-bind), add a lint analyzer (/add-linter-check).
  4. Update docs/lang.md if user-facing (it is embedded and served by elps doc --guide).
  5. Write Go and/or lisp tests (below), then /verify.

Static migration diagnostics

When a correctness fix changes previously accepted behavior, ship a reliable static diagnostic for recognizable affected source patterns: elps lint for Lisp source (/add-linter-check), elpsvet for Go embedding or implementation invariants (/elpsvet). Point at the affected expression, explain the replacement, and test both the broken pattern and valid lookalikes. Where dynamic bindings, runtime data or opaque macros prevent a complete check, document the limits — never present a partial check as proof that a program is compatible.

4. Write Tests

For builtins/ops/macros — elpstest.TestSuite

Each row is a positional {expression, expected-result, expected-output} triple; an expected error is written as its rendered message:

func TestMyBuiltin(t *testing.T) {
	tests := elpstest.TestSuite{
		{"my-builtin", elpstest.TestSequence{
			{`(my-builtin "arg1" 42)`, `"expected-result"`, ""},
			{`(my-builtin)`, "test:1:1: lisp:my-builtin: invalid number of arguments: 0", ""},
		}},
	}
	elpstest.RunTestSuite(t, tests)
}

For linter checks — See /add-linter-check skill

For stdlib packages — See /add-stdlib-package skill

For bug fixes — Write a regression test that:

  1. Fails without the fix (verify this first)
  2. Passes with the fix

5. Branch Naming

Create a branch before starting work:

  • Features: feature/<short-description>
  • Bug fixes: fix/<short-description>
  • Refactors: refactor/<short-description>
  • Issue-driven: issue-<N>/<short-description>

Never commit or push to main; the /pr skill has the guard.

6. Verify

After implementation, run the full verification pipeline. See /verify skill.

Checklist

  • Read target files before modifying
  • Implementation follows existing code style
  • Docstring included (if adding builtin/op/macro)
  • Tests written (regression test for bug fixes)
  • make test passes
  • make static-checks passes
  • ./elps doc -m passes (if touching builtins)
  • docs/lang.md updated (if user-facing feature)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall