Skip to content

luthersystems/elps / .claude/skills/fuzz

/fuzz — Native Go Fuzzing Skill

Runs the repository's go test -fuzz targets, adds new ones, and triages crashers. CI runs .github/workflows/fuzz.yml: 30s per target on PRs, 10m per target nightly, sharded.

Trigger

Use when asked to fuzz, add or change a fuzz target, investigate a fuzz CI failure, or triage a file under some package's testdata/fuzz/<Target>/.

Run

make fuzz-list                                  # authoritative list of targets (discovered with go test -list)
make fuzz                                       # every target, 30s each (the PR budget)
make fuzz FUZZTIME=10m                          # the nightly budget
make fuzz FUZZ_PKGS=./parser/rdparser/...       # one package
go test -run='^$' -fuzz='^FuzzEval$' -fuzztime=60s ./lisp/   # one target by hand

scripts/fuzz.sh refuses to run without a parsable FUZZTIME and caps every invocation with a hard -timeout; never write a -fuzz invocation without -fuzztime (CI checks for that). FUZZ_TAGS=elpscheck fuzzes the tagged build, whose targets are otherwise invisible.

Plain go test ./... (and so make test) replays every committed seed and crasher in testdata/fuzz/ as a regression case.

Triage a crasher

  1. Find it: go test -fuzz writes testdata/fuzz/<Target>/<hash> in the target's package; CI uploads the same file as an artifact.
  2. Reproduce without fuzzing: go test -run='^<Target>$/^<hash>$' ./<pkg>/.
  3. Classify: a real defect in the code under test, a harness defect (budget too small for a terminating program, a watchdog on wall clock), or a toolchain race. make fuzz-classify-test covers how scripts/fuzz.sh reports each; read its output before assuming the product is at fault.
  4. Fix the root cause with a focused regression test, and commit the crasher file so go test keeps replaying it.

Add a target

  1. Put it in the package's fuzz_test.go (or <area>_fuzz_test.go), named FuzzXxx. Discovery is automatic — there is no registration table.
  2. Seed from internal/fuzzseed (All(), LispSources(), Adversarial(), Pathological()) plus target-specific adversarial input.
  3. Assert a property with teeth (round-trip equality, no internal panic, termination), not merely "did not crash".
  4. Any termination watchdog must use internal/fuzzwatch (scheduled-time budget, with a floor enforced by its call-site guard test), not a bare time.After.
  5. Run make fuzz-budget-check: each new target adds a FUZZTIME to the nightly sweep, and the check derives whether fuzz.yml's timeout-minutes still holds. Follow its printed options rather than raising the timeout by hand.
  6. After touching scripts/fuzz.sh or fuzz.yml, run make ci-gates-test and make fuzz-classify-test.

Hazards that are load-bearing

Read the header comment of the target before changing it; these are the condensed reasons.

  • Evaluator (lisp.FuzzEval, lisp/eval_fuzz_test.go) — evaluation is Turing-complete and go test -fuzz has no per-input deadline, so every evaluation runs under explicit budgets (WithMaxSteps, WithMaxTailIterations, WithMaximumPhysicalStackHeight, WithMaxAlloc, a context deadline) plus a watchdog. env.eval recovers Go panics into an ordinary-looking *LVal, so the real assertion is lisp.IsInternalPanic(result) == false. Eval seeds are executed, so internal/fuzzseed/evalseed.go is hand-written and does not seed from LispSources(). Seeds are split: EvalRunaway must error (a budget stopping an infinite loop is correct) and EvalTerminating must complete without error (a bounded program tripping a budget is a defect).
  • Debugger (lisp/x/debugger.FuzzDebugEval) — attaching a debugger disables tail-call optimisation and stamps MacroExpansionInfo onto macro-expanded nodes, so it is a different eval path from FuzzEval's.
  • Language server (lsp.FuzzLSPSession, lsp/lsp_fuzz_test.go) — a fuzzer-chosen sequence of requests against fuzzer-chosen documents and cursor positions; the only target that reaches analysis/ and lint/. The server has four blanket recover()s, so "no crash" means nothing until they are accounted for; the header documents which are neutralised, which is detected, and which is not covered.

Checklist

  • Target asserts a real property, with budgets and a fuzzwatch watchdog if it evaluates
  • Seeds come from internal/fuzzseed
  • make fuzz-budget-check passes after adding a target
  • Crasher fixed at the root cause and its testdata/fuzz/ file committed
  • make test passes (replays the corpus)
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