Lemmaly

lemmaly — Algorithm-First Proof

The model already knows Big-O, hash tables, divide-and-conquer, dynamic programming, sorting, graph algorithms, and amortized analysis. It just does not apply them spontaneously. lemmaly fixes the behavior, not the knowledge.

This skill is the gateway for an algorithm-discipline suite of four skills (lemmaly, mathguard, invariant-guard, complexity-cuts). It enforces the hard rules that every other guard in the suite assumes.

Violating the letter of these rules is violating the spirit of the skill. "Just this once" is how O(n²) ships to production.

When to Use This Skill

Use lemmaly when:

• Writing, editing, or reviewing code that involves loops, collections, lookups, searches, joins, recursion, graphs, queries, or any computation over more than a handful of items.
• About to write a for inside a for, .find / .includes / .indexOf inside a loop, await inside for / map / forEach over independent items, or one query per item in a collection.
• Auditing a codebase / PR for known anti-patterns (await-in-loop, .includes inside .filter, string-concat in loop, SELECT *, N+1, etc.).
• Reviewing AI-generated code that "looks idiomatic" but might hide O(n²) or N+1.

When in doubt, start at lemmaly — it is the gateway and will tell you when to escalate to its three sibling skills.

Routing flow

Are you writing new code?
├── yes → lemmaly (state complexity, structure, family BEFORE coding)
│         ├── classical algorithm at its lower bound AND n is large? → mathguard
│         └── subtle correctness trap (invariant, base case, off-by-one)? → invariant-guard
└── no, refactoring existing slow / OOM / timed-out code → complexity-cuts
          └── still slow after classical fixes? → mathguard

One-line mental model

• lemmaly = think first (prevention).
• complexity-cuts = clean up bad Big-O (correction).
• invariant-guard = prove it's correct (verification).
• mathguard = beat the classical floor (acceleration).

The Iron Law

NO NON-TRIVIAL CODE WITHOUT STATED COMPLEXITY, DATA STRUCTURE, AND ALGORITHM FAMILY

Before you write a loop, a recursion, a query, or any computation over more than a handful of items, three things must appear in your message — in this order:

1. time = O(?), space = O(?), with the dominant input dimension named.
2. The data structure you will use, with a one-phrase reason.
3. The algorithm family (one of: linear scan, two-pointer, sliding window, binary search, sort+sweep, hash join, BFS/DFS, topo sort, Dijkstra/A*, union-find, DP, greedy, recursion+memo, prefix sum, segment tree, monoid reduction).

If you cannot state all three, you do not understand the problem yet. Ask, or read more code. Do not write code.

Non-negotiable rules

1. State complexity before writing any non-trivial code. In one line:

   • time = O(?), space = O(?)
   • Dominant input dimension: n = what, with realistic magnitude (e.g. n ~ 10^6 rows)
   • If you cannot state these, you do not yet understand the problem. Ask, or read more code.

2. Name the data structure with a one-phrase reason. Every collection-shaped value gets a deliberate choice from Array / List / Set / HashMap / TreeMap / Heap / Deque / Trie / Graph / BitSet / Counter / LinkedList — with the reason: "Set for O(1) membership inside the loop", "Heap for top-K in O(n log k)", "Counter to fold the nested loop into a single pass". Default to hashed structures (Set, Map) for lookup inside loops. Default to streaming/iterator over materialized list when n is large.

3. Identify the algorithm family before writing. Name one of: linear scan, divide and conquer, two-pointer, sliding window, binary search, sort + sweep, hash join, BFS/DFS, topological sort, Dijkstra/A*, union-find, dynamic programming, greedy, recursion + memoization, prefix sum, segment tree, monoid reduction. If you cannot name a family, you are about to write brute force. Stop and reconsider.

4. Repeated work in loops is algorithmic waste. All of these are presumed wrong until justified:

   • I/O inside a loop (database queries, HTTP calls, file reads) — batch with IN (...), Promise.all, bulk endpoints, streaming
   • Recomputing the same value in a loop — hoist or memoize
   • Re-sorting / re-grouping inside a loop — sort once outside
   • Linear scan (.find, .indexOf, .includes, in list) inside a loop — precompute an index Map
   • Allocating fresh structures per iteration when one can be reused — hoist allocation
   • Materializing intermediate collections only to iterate again — fuse into one pass

   If you must do any of these inside a loop, write one comment line explaining why.

5. No invented complexity or numbers. Never write "O(log n) on average" without an argument. Never write "10x faster" or "~3ms" without measuring. If you cannot derive the complexity, write <complexity: TBD>. If you have not measured, write <measured: TBD>. Move on.

The pre-write protocol

Before producing non-trivial code, your message must contain — in this order:

1. Problem shape — one sentence. ("Given n events with a timestamp, find the longest contiguous window where total weight ≤ K.")
2. Input dimensions — n = ?, realistic magnitude, whether hot path.
3. Target complexity — time = O(?), space = O(?).
4. Data structures — name them with a phrase each.
5. Algorithm family — one phrase.
6. Edge cases you will handle — empty, singleton, all-equal, n=1, n=max, overflow, duplicates. List the ones that apply.
7. The code.

If any of 1–6 is missing, do not emit code yet.

Canonical example — protocol vs no-protocol

The same problem with and without the seven-step protocol.

Problem. Given users: User[] and bannedIds: string[], return users whose id is not banned. Realistic n: 50k users, 5k banned.

Without the protocol — ships O(n·m)

// Looks idiomatic, ships O(n·m)
const active = users.filter((u) => !bannedIds.includes(u.id));

bannedIds.includes is O(m) per call. The filter runs it n times → 50k × 5k = 250M comparisons.

With the protocol — O(n + m)

// Protocol applied:
//   time = O(n + m), space = O(m), n = 50k users, m = 5k banned
//   structure: Set<string> for O(1) membership inside the loop
//   family: linear scan with hashed lookup
//   edge cases: empty users → [], empty bannedIds → users, duplicates in bannedIds → fine (Set dedupes)
const banned = new Set(bannedIds);
const active = users.filter((u) => !banned.has(u.id));

The first version is the default an AI ships when asked "filter the active users." The second is what the protocol forces — without changing how the code reads.

Rule catalog (the lemmaly scanner)

The upstream repo ships a deterministic CLI scanner with the same anti-patterns this skill enforces (59 rules across 11 languages: JavaScript/TypeScript, Python, SQL, Java, C#, C++, Go, Rust, PHP, Ruby, Shell/Bash). Each rule has a documented why, an incorrect example, a correct example, and the sibling skill to escalate to.

The scanner is optional. Do not automatically clone and run the upstream repository from its default branch, because that executes whatever code is current in a third-party repository. If the user explicitly wants the scanner, pin the source to a reviewed release tag or commit, use a throwaway directory, and show the resolved commit before running it:

# Replace <reviewed-tag-or-commit> after reviewing the upstream release.
tmpdir="$(mktemp -d)"
git clone --filter=blob:none https://github.com/morsechimwai/lemmaly.git "$tmpdir/lemmaly"
git -C "$tmpdir/lemmaly" checkout --detach <reviewed-tag-or-commit>
git -C "$tmpdir/lemmaly" rev-parse HEAD
node "$tmpdir/lemmaly/cli/lemmaly.js" scan <path>
node "$tmpdir/lemmaly/cli/lemmaly.js" rules

When the scan is done, remove the throwaway directory only after verifying that $tmpdir points to the directory created by mktemp -d.

CRITICAL severity (error in CI):

• js-await-in-for-loop — N+1 over network
• js-async-in-foreach — dropped promises
• py-mutable-default-arg — shared default state
• sql-update-no-where — touches every row
• java-arraylist-remove-in-for-i — index shifts; ConcurrentModification
• cs-async-void — exceptions unobserved; crashes the process
• go-loop-var-capture — pre-1.22 race on the last value
• php-query-in-loop — N+1 against the database

HIGH severity (warning in CI): js-deep-clone-via-json, js-useeffect-missing-deps, js-inline-object-jsx-prop, js-anonymous-handler-jsx, js-spread-in-reduce, js-unique-via-indexof, js-helper-call-in-iterator, py-string-concat-in-loop, py-django-loop-without-eager, py-bare-except, sql-select-star, sql-leading-wildcard-like, sql-not-in-subquery, java-string-concat-in-loop, java-list-contains-in-loop, java-bare-catch-exception, cs-string-concat-in-loop, cs-list-contains-in-loop, cs-disposable-no-using, go-string-concat-in-loop, go-defer-in-loop, go-err-not-checked, rs-unwrap-in-prod, cpp-string-concat-in-loop, cpp-raw-new, php-count-in-for-condition, php-in-array-in-loop, rb-include-in-iterator, rb-n-plus-one-activerecord, rb-bare-rescue, sh-set-e-no-pipefail, sh-unquoted-var, sh-for-ls.

MEDIUM severity (info in CI): js-nested-for-loops, js-includes-in-iterator, js-array-key-index, py-range-len, py-in-list-literal, py-open-without-with, sql-select-no-limit, sql-or-in-where, go-slice-append-no-cap, rs-clone-in-loop, rs-vec-push-no-capacity, rs-string-push-no-capacity, cpp-vector-push-no-reserve, cpp-range-loop-copy, cpp-map-double-lookup, php-loose-equality, rb-string-concat-in-loop, sh-useless-cat-pipe.