luthersystems/elps / .claude/skills/audit
audit
Verified/audit — Codebase Audit Skill
Performs a systematic, multi-category audit of the ELPS codebase.
Trigger
Use when asked to audit the codebase, find bugs, improve security, review code quality, or perform a comprehensive health check.
Workflow
1. Create Branch
git checkout main && git pull origin main
git checkout -b audit/<focus-or-date>
2. Scan Each Category
Work through categories systematically. For each finding: understand it, fix it, write a test if applicable, and commit as a logical unit.
Category 1: Bugs
Scan for:
- Returned
*LValerrors (LError) not checked and propagated - Walkers that treat values as trees: nested sharing (
(set! x (list x x))) makes them exponential (lisp/sharing.gohas the budget and memo pattern) - Builtins whose work grows with value size but charge no steps or skip
CheckAlloc
Where to look: lisp/, parser/, formatter/, lint/
Category 2: Security
Scan for:
- File access in builtins and the CLI: path traversal and symlink following (
os.Open,os.ReadFile,filepath.Walk) - Limits a program can bypass: the step budget,
MaxAlloc, and context cancellation
Run: make static-checks (gosec is enabled in .golangci.yml), make elpsvet (shared-state and native-payload invariants; /elpsvet), and a make fuzz pass over the packages in scope (/fuzz)
Where to look: lisp/lisplib/, cmd/, repl/
Category 3: Performance
Scan the eval loop and parser for allocations per call. Measure on the
whole-program benchmarks (BenchmarkWorkload) before and after, per the
/benchmark skill.
Where to look: lisp/env.go (eval loop), lisp/builtins.go, parser/rdparser/
Category 4: Tests
Scan for coverage gaps in error paths, and for tests that depend on shared state or wall-clock time.
Run: go test -cover ./... and examine coverage percentages.
Where to look: All _test.go files, compare against source files
Category 5: Documentation
Scan for:
- Missing docstrings:
./elps doc -m - Stale docs in
docs/lang.md(features added but docs not updated) - Incorrect help text (description doesn't match behavior)
- Missing examples in documentation
Where to look: docs/lang.md, docs/lint-checks.md, builtin/op/macro definitions, AGENTS.md, .claude/skills/
Category 6: Code Quality
Run make static-checks (mind the version-skew note in AGENTS.md before
removing a //nolint), and look for builtins that handle errors differently
from their neighbours.
Where to look: Entire codebase
3. Group Commits Logically
Organize fixes into coherent commits by category and sub-topic:
fix: resolve nil dereference in handler-bind error pathsecurity: validate file paths before openingperf: pre-size maps in parser initializationtest: add coverage for edge cases in builtin arithmeticdocs: update lang.md for new builtins
4. Verify
Run full /verify pipeline after all fixes.
5. Create PR
Follow /pr skill. Structure the PR body with categorized findings:
## Summary
Systematic codebase audit covering N categories with M fixes.
### Bugs (N fixes)
- Fix nil dereference in ...
- Fix off-by-one in ...
### Security (N fixes)
- Validate file paths in ...
### Performance (N fixes)
- Pre-size parser maps ...
### Tests (N additions)
- Add edge case coverage for ...
### Documentation (N updates)
- Update lang.md for ...
### Code Quality (N fixes)
- Resolve the work marker in ...
Scoped Audits
For targeted audits, focus on a single category or package:
/audit security— Security-focused scan only/audit lisp/— Audit only the interpreter core/audit tests— Test coverage and quality only
Checklist
- All 6 categories scanned (or scoped subset)
- Findings fixed with tests where applicable
- Commits grouped logically by category
- No regressions introduced (benchmarks stable)
- Full verify pipeline passes
- PR created with categorized summary
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |