[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M770EYRB3H4FJV67T41CCXME":3,"skill-same:01M770EYRB3H4FJV67T41CCXME":65},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":43,"commitSha":44,"skillDirectory":45,"forksCount":14,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":48,"ownerDescription":49,"updatedAt":50,"install":51,"resources":64},"01M770EYRB3H4FJV67T41CCXME","invariant-guard",null,"Correctness-first: forces writing the function contract, loop invariant, termination argument, and edge cases BEFORE code. Catches Boyer-Moore, leftmost binary search, QuickSelect traps.","haresh-sai06\u002FSapSynk-AI","haresh-sai06","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F180730984?v=4","01M75NJVH4TXYCE7FW7YVMSVFF","Haresh Sainaath S","01M75NJVHTCW1Z2P6MNCYGNSTJ",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity__invariant-guard\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: invariant-guard\ndescription: \"Correctness-first: forces writing the function contract, loop invariant, termination argument, and edge cases BEFORE code. Catches Boyer-Moore, leftmost binary search, QuickSelect traps.\"\nrisk: safe\nsource: community\nsource_repo: morsechimwai\u002Flemmaly\nsource_type: community\ndate_added: \"2026-05-26\"\nauthor: morsechimwai\ntags: [algorithms, correctness, loop-invariants, contracts, edge-cases, verification]\ntools: [claude-code, antigravity, cursor, gemini-cli, codex-cli]\nlicense: \"Apache-2.0\"\nlicense_source: \"https:\u002F\u002Fgithub.com\u002Fmorsechimwai\u002Flemmaly\u002Fblob\u002Fmain\u002FLICENSE\"\n---\n\n# invariant-guard — Correctness-First Coding\n\nThe model knows what a loop invariant is. It knows recursion needs a base case. It knows about empty lists, integer overflow, and the difference between `\u003C` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.\n\ninvariant-guard fixes the behavior. State the invariants. State the base case. State the termination argument. State the edge cases. Then write the code — and verify that the code maintains what you stated.\n\n**Violating the letter of these rules is violating the spirit of the skill.** \"I know this algorithm\" is the exact rationalization that ships off-by-one and missing-postcondition bugs.\n\n## When to Use This Skill\n\nUse **invariant-guard** when writing or reviewing algorithms where the obvious implementation is subtly wrong:\n\n- Postcondition stronger than the loop's natural invariant: Boyer–Moore majority, Floyd's cycle detection, leftmost vs any binary search, QuickSelect partition.\n- In-place mutation with read+write pointers: dedup-in-place, partition, rotate.\n- Recursion with multiple parameters or accumulator state.\n- Off-by-one suspects with duplicates, empty inputs, boundary values.\n- Iterative refinements that must terminate: fixed-point, Newton, EM.\n- Any function where you catch yourself thinking \"I know this algorithm\" — the trap is usually in the contract, not the loop body.\n\nPairs with `lemmaly` (picks the algorithm) and `mathguard` (picks the math). Load `invariant-guard` *after* the algorithm has been chosen and *before* the loop body is written.\n\n## The Iron Law\n\n```text\nNO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT\n```\n\nIf you cannot write the invariant in one sentence, you have not designed the loop. Write code anyway and you are coding by guess — and the bug will be in the case you did not enumerate.\n\n## Non-negotiable rules\n\n1. **Every loop gets a one-line invariant.** Before writing any loop, state in one sentence what is true at the top of every iteration. Examples:\n   - \"At loop top: `result` contains the sum of `a[0..i)`.\"\n   - \"At loop top: `lo ≤ target_position ≤ hi`.\"\n   - \"At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice.\"\n\n   If you cannot write the invariant in one sentence, you have not designed the loop yet.\n\n2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:\n   - \"`hi − lo` strictly decreases each iteration.\"\n   - \"`i` increases by 1 and is bounded above by `n`.\"\n   - \"`stack.length` strictly decreases each pop; nothing pushes inside this branch.\"\n\n   No termination argument, no loop.\n\n3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:\n   - The base case(s) — the smallest inputs that return without recursing.\n   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).\n   - The combination — how the recursive results combine into the answer.\n\n   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)\n\n4. **List edge cases before writing, not after.** For every function operating on a collection or number, list which of these apply and how they behave:\n   - Empty input (`[]`, `\"\"`, `null`, `undefined`, `None`).\n   - Singleton (`[x]`).\n   - All-equal elements.\n   - Already-sorted \u002F reverse-sorted input.\n   - Duplicates (when uniqueness is assumed).\n   - Negative numbers, zero, exactly the boundary value.\n   - Integer overflow \u002F underflow at the type max\u002Fmin.\n   - NaN, ±Infinity, `-0`, denormals (for floats).\n   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.\n   - Concurrent modification while iterating.\n\n   The cases that apply must each have a one-phrase expected behavior written down.\n\n5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:\n   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).\n   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).\n   - Non-empty list type when the function requires at least one element.\n   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).\n\n   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.\n\n## The pre-write protocol\n\nBefore producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:\n\n1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.\n2. **Loop invariants** — one per loop. (Rule 1.)\n3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)\n4. **Base cases and measure** — for recursion. (Rule 3.)\n5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)\n6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)\n7. **The code.**\n8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.\n\nIf any of 1–6 is missing, do not emit code.\n\n## Worked trap — Boyer–Moore majority vote\n\nThis is the canonical \"the trap is in the contract, not the loop body\" case.\n\n**Naive baseline (what gets shipped without the skill):**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  let candidate = arr[0], count = 0;\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  return candidate;   \u002F\u002F BUG: returns the candidate even when no majority exists\n}\n```\n\nThis implementation fails on `[1,2,3]` (returns `3`, expected `null`) and `[2,2,1,1]` (returns `1`, expected `null`). The voting loop is correct; the postcondition is wrong.\n\n**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:\n\n> Returns `x` iff `count(x, arr) > arr.length \u002F 2`; else `null`.\n\nThen writing **step 2 (loop invariant)** forces the invariant of the voting pass:\n\n> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.\n\nThese two statements are not equivalent. The loop invariant guarantees \"if a majority exists, it is the candidate\" — not \"the candidate is a majority.\" Once you write both down, the gap is visible: you need a second pass to verify, or the postcondition is unmet.\n\n**Correct implementation that survives the protocol:**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  \u002F\u002F Pass 1: vote.\n  let candidate = arr[0], count = 0;\n  \u002F\u002F inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  \u002F\u002F Pass 2: verify — the voting invariant is strictly weaker than the postcondition.\n  let tally = 0;\n  \u002F\u002F inv: tally = count of candidate in arr[0..i).\n  for (const x of arr) if (x === candidate) tally++;\n  return tally * 2 > arr.length ? candidate : null;\n}\n```\n\n**Pattern to generalize.** The same trap appears in:\n\n- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.\n- **Two-pointer \"find any\"** vs **\"find leftmost\"** — the loop invariant for one does not satisfy the postcondition of the other.\n- **QuickSelect partition** — the loop returns a position; the postcondition is that the element at that position is the k-th smallest. Off by one in the partition invariant silently breaks it.\n- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.\n\nIn every case: **write the postcondition first; write the loop invariant second; check that the second implies the first. If not, you are missing a pass, a check, or an auxiliary state.**\n\n## Canonical example — binary search for the leftmost match\n\nMost \"I know binary search\" implementations are written for \"find any match.\" The trap is the postcondition.\n\n**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.\n\n### Without the protocol — returns any match\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  let lo = 0, hi = a.length - 1;\n  while (lo \u003C= hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] === target) return mid;       \u002F\u002F returns ANY occurrence\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid - 1;\n  }\n  return -1;\n}\n\u002F\u002F leftmost([1,2,2,2,3], 2) → may return 2, not 1\n```\n\nThe loop invariant (\"target lies in `a[lo..hi]` if anywhere\") is satisfied. But the postcondition (\"returned index is the *smallest* `i` with `a[i] === target`\") is strictly stronger. The loop body's early return abandons the search before reaching the leftmost.\n\n### With the protocol — contract-driven leftmost\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  \u002F\u002F contract:\n  \u002F\u002F   pre:  a is sorted ascending\n  \u002F\u002F   post: returns smallest i with a[i] === target, or -1 if absent\n  let lo = 0, hi = a.length;                 \u002F\u002F half-open [lo, hi)\n  \u002F\u002F inv: every index \u003C lo has a[i] \u003C target; every index ≥ hi has a[i] > target OR is past leftmost match\n  \u002F\u002F term: hi - lo strictly halves each iteration\n  while (lo \u003C hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid;\n  }\n  \u002F\u002F exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target\n  return lo \u003C a.length && a[lo] === target ? lo : -1;\n}\n```\n\nSame loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.\n\n## Common invariant patterns to reach for\n\n| Loop \u002F algorithm shape | Canonical invariant | Termination |\n|---|---|---|\n| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |\n| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |\n| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |\n| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |\n| BFS | every node at distance \u003C d has been popped; queue contains some at distance d | strict node count decrease per pop |\n| DFS \u002F recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |\n| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |\n| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |\n| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |\n| In-place partition | `a[0..i)` \u003C pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |\n\n## Edge case table — defaults to consider\n\n| Input shape | Cases to check |\n|---|---|\n| Array \u002F list | empty, singleton, all-equal, sorted, reversed, with duplicates |\n| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |\n| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |\n| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |\n| Map \u002F dict | empty, missing key (default vs error), key collision semantics |\n| Tree \u002F graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |\n| Stream \u002F iterator | empty, infinite, single yield, exception mid-iteration |\n| Time \u002F date | DST transition, leap second\u002Fday, timezone offset, epoch boundary |\n| Concurrent | empty contention, single thread, max contention, cancellation mid-op |\n\n## Output discipline\n\nCode you emit must:\n\n- Have one comment per loop stating the invariant (use `\u002F\u002F inv:` or `# inv:`).\n- Have one comment per recursion stating the base case and measure.\n- Handle every edge case you listed in step 5, or explicitly delegate (\"throws on empty — caller responsibility\").\n- Assert preconditions at function entry when the language supports it cheaply.\n- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.\n\n## When to escalate or redirect\n\n- The function is performance-critical and you have not picked the algorithm — go back to **`lemmaly`** first; pick the algorithm, then state its invariants here.\n- The technique is mathematical (probabilistic, FFT, geometry) — load **`mathguard`**; invariants for approximate algorithms include ε-bounds, not equality.\n- The code is concurrent — invariants must account for interleaving; explicitly state \"single-threaded only\" if that is the assumption.\n\n## Rationalizations to watch for\n\n| Excuse | Reality |\n| --- | --- |\n| \"I know this algorithm — single pass, done.\" | Knowing the loop ≠ knowing the contract. The trap usually lives in the postcondition the loop does not enforce. |\n| \"I traced it in my head, it works.\" | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |\n| \"Edge cases are obvious.\" | Then write them down in 30 seconds. If they are obvious, the table is cheap. If they are not, the table just saved you. |\n| \"Tests will catch it.\" | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |\n| \"The postcondition is implied.\" | If it were, the natural loop invariant would equal it. When they differ (Boyer–Moore, leftmost search, QuickSelect), you need a second pass, an extra check, or auxiliary state. |\n| \"Adding a verification pass feels redundant.\" | Boyer–Moore voting + verification is still O(n). \"Feels redundant\" is the rationalization that ships the bug. |\n\n## Red flags — STOP and write the invariant first\n\n- About to write `while (...)` without having stated what is true on entry.\n- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.\n- About to recurse without naming the base case in this message.\n- About to write `\u002F\u002F TODO: handle empty` — handle it now or change the type so empty is impossible.\n- About to use `==` on floats.\n- About to compare across signed\u002Funsigned or across types where overflow rolls.\n- About to silently swallow an error in the middle of a loop (\"just continue\").\n- Tests pass but you did not actually state what the function guarantees.\n- \"It works on the examples I tried.\"\n\n## Verification checklist\n\nBefore claiming the function is correct:\n\n- [ ] Every loop has a one-line `\u002F\u002F inv:` comment in code.\n- [ ] Every loop has a termination argument written down (in comment or PR description).\n- [ ] Every recursion names its base case and measure in code.\n- [ ] The function's postcondition is written and is implied by the exit state of the last loop.\n- [ ] Every applicable edge case from the table has a test or an explicit \"delegated to caller\" note.\n- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).\n- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.\n- [ ] For approximate\u002Frandomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.\n\nCannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.\n\n## Limitations\n\n- **Not an automated prover.** invariant-guard requires the author to *write* invariants; it does not mechanically check them. Pair with property-based tests for stronger evidence.\n- **Concurrency is out of scope by default.** Stated invariants assume single-threaded execution unless explicitly extended; multi-threaded reasoning needs additional happens-before \u002F linearizability arguments.\n- **Float and overflow edge cases are language-specific.** The edge-case table is a checklist, not a substitute for understanding your language's numeric semantics.\n- **Will slow down trivial code.** For one-liners that obviously cannot fail, the protocol is overhead; reserve it for non-trivial loops, recursion, and in-place mutation.\n- **Documentation is the only enforcement.** If the author skips writing the invariants, this skill cannot detect that — pair with code review or a PR template that asks for the contract.\n\n## The thesis, in one line\n\n> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**\n\n## Related Skills\n\n- `lemmaly` — algorithm choice must be settled before invariants; load lemmaly first if the algorithm family is unclear.\n- `mathguard` — ε-bounded postconditions for approximate \u002F randomized algorithms.\n- `complexity-cuts` — if 3+ optimization transformations have failed tests, the bug is a missing contract, not a missing optimization — escalate here.\n","# invariant-guard — Correctness-First Coding\n\nThe model knows what a loop invariant is. It knows recursion needs a base case. It knows about empty lists, integer overflow, and the difference between `\u003C` and `≤`. It just does not write these down before producing code, so it ships subtle correctness bugs that tests do not catch.\n\ninvariant-guard fixes the behavior. State the invariants. State the base case. State the termination argument. State the edge cases. Then write the code — and verify that the code maintains what you stated.\n\n**Violating the letter of these rules is violating the spirit of the skill.** \"I know this algorithm\" is the exact rationalization that ships off-by-one and missing-postcondition bugs.\n\n## When to Use This Skill\n\nUse **invariant-guard** when writing or reviewing algorithms where the obvious implementation is subtly wrong:\n\n- Postcondition stronger than the loop's natural invariant: Boyer–Moore majority, Floyd's cycle detection, leftmost vs any binary search, QuickSelect partition.\n- In-place mutation with read+write pointers: dedup-in-place, partition, rotate.\n- Recursion with multiple parameters or accumulator state.\n- Off-by-one suspects with duplicates, empty inputs, boundary values.\n- Iterative refinements that must terminate: fixed-point, Newton, EM.\n- Any function where you catch yourself thinking \"I know this algorithm\" — the trap is usually in the contract, not the loop body.\n\nPairs with `lemmaly` (picks the algorithm) and `mathguard` (picks the math). Load `invariant-guard` *after* the algorithm has been chosen and *before* the loop body is written.\n\n## The Iron Law\n\n```text\nNO LOOP OR RECURSION WITHOUT A WRITTEN INVARIANT AND TERMINATION ARGUMENT\n```\n\nIf you cannot write the invariant in one sentence, you have not designed the loop. Write code anyway and you are coding by guess — and the bug will be in the case you did not enumerate.\n\n## Non-negotiable rules\n\n1. **Every loop gets a one-line invariant.** Before writing any loop, state in one sentence what is true at the top of every iteration. Examples:\n   - \"At loop top: `result` contains the sum of `a[0..i)`.\"\n   - \"At loop top: `lo ≤ target_position ≤ hi`.\"\n   - \"At loop top: `seen` contains every element processed so far; `dups` contains every element that appeared at least twice.\"\n\n   If you cannot write the invariant in one sentence, you have not designed the loop yet.\n\n2. **Every loop gets a one-line termination argument.** Name the quantity that strictly decreases (or strictly increases toward a bound) on every iteration. Examples:\n   - \"`hi − lo` strictly decreases each iteration.\"\n   - \"`i` increases by 1 and is bounded above by `n`.\"\n   - \"`stack.length` strictly decreases each pop; nothing pushes inside this branch.\"\n\n   No termination argument, no loop.\n\n3. **Every recursion gets an explicit base case and a measure.** Before writing a recursive function, state:\n   - The base case(s) — the smallest inputs that return without recursing.\n   - The measure — a non-negative integer that strictly decreases on every recursive call (e.g. `len(xs)`, `hi − lo`, `depth`, `n`).\n   - The combination — how the recursive results combine into the answer.\n\n   No base case + measure, no recursion. (Mutual recursion: state the measure across the cycle.)\n\n4. **List edge cases before writing, not after.** For every function operating on a collection or number, list which of these apply and how they behave:\n   - Empty input (`[]`, `\"\"`, `null`, `undefined`, `None`).\n   - Singleton (`[x]`).\n   - All-equal elements.\n   - Already-sorted \u002F reverse-sorted input.\n   - Duplicates (when uniqueness is assumed).\n   - Negative numbers, zero, exactly the boundary value.\n   - Integer overflow \u002F underflow at the type max\u002Fmin.\n   - NaN, ±Infinity, `-0`, denormals (for floats).\n   - Off-by-one boundaries: index 0, index n−1, index n, length 0, length 1.\n   - Concurrent modification while iterating.\n\n   The cases that apply must each have a one-phrase expected behavior written down.\n\n5. **Make illegal states unreachable, not just unhandled.** Prefer encoding constraints in types and structure so the wrong state cannot be constructed:\n   - Sum type over boolean flag soup (`Loading | Loaded(data) | Error(msg)` not `{loading, data, error}`).\n   - Newtype for IDs that must not be swapped (`UserId` vs `OrderId`).\n   - Non-empty list type when the function requires at least one element.\n   - Parsed value at the boundary, not validated repeatedly downstream (parse-don't-validate).\n\n   If the language cannot encode it, write the invariant as a comment and assert it at the boundary.\n\n## The pre-write protocol\n\nBefore producing non-trivial code that has loops, recursion, or non-trivial state, your message must contain — in this order:\n\n1. **Function contract** — preconditions, postconditions, and what the function returns. One line each.\n2. **Loop invariants** — one per loop. (Rule 1.)\n3. **Termination arguments** — one per loop or recursion. (Rules 2, 3.)\n4. **Base cases and measure** — for recursion. (Rule 3.)\n5. **Edge case table** — bullets, one per applicable case, with expected behavior. (Rule 4.)\n6. **Illegal states made unrepresentable** — name the types or asserts that enforce invariants. (Rule 5.)\n7. **The code.**\n8. **Self-check** — one line per loop confirming the invariant holds at top, body preserves it, and exit implies postcondition.\n\nIf any of 1–6 is missing, do not emit code.\n\n## Worked trap — Boyer–Moore majority vote\n\nThis is the canonical \"the trap is in the contract, not the loop body\" case.\n\n**Naive baseline (what gets shipped without the skill):**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  let candidate = arr[0], count = 0;\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  return candidate;   \u002F\u002F BUG: returns the candidate even when no majority exists\n}\n```\n\nThis implementation fails on `[1,2,3]` (returns `3`, expected `null`) and `[2,2,1,1]` (returns `1`, expected `null`). The voting loop is correct; the postcondition is wrong.\n\n**Why the protocol catches it.** Writing **step 1 (function contract)** forces the postcondition in plain language:\n\n> Returns `x` iff `count(x, arr) > arr.length \u002F 2`; else `null`.\n\nThen writing **step 2 (loop invariant)** forces the invariant of the voting pass:\n\n> If a strict majority element exists in `arr`, it equals `candidate` when the loop exits.\n\nThese two statements are not equivalent. The loop invariant guarantees \"if a majority exists, it is the candidate\" — not \"the candidate is a majority.\" Once you write both down, the gap is visible: you need a second pass to verify, or the postcondition is unmet.\n\n**Correct implementation that survives the protocol:**\n\n```typescript\nfunction findMajority(arr: number[]): number | null {\n  if (arr.length === 0) return null;\n  \u002F\u002F Pass 1: vote.\n  let candidate = arr[0], count = 0;\n  \u002F\u002F inv: if a strict majority exists in arr, it equals candidate at every count===0 reset.\n  for (const x of arr) {\n    if (count === 0) candidate = x;\n    if (x === candidate) count++; else count--;\n  }\n  \u002F\u002F Pass 2: verify — the voting invariant is strictly weaker than the postcondition.\n  let tally = 0;\n  \u002F\u002F inv: tally = count of candidate in arr[0..i).\n  for (const x of arr) if (x === candidate) tally++;\n  return tally * 2 > arr.length ? candidate : null;\n}\n```\n\n**Pattern to generalize.** The same trap appears in:\n\n- **Floyd's cycle detection** — finding the meeting point tells you a cycle exists, *not* where it starts. You need a second walk.\n- **Two-pointer \"find any\"** vs **\"find leftmost\"** — the loop invariant for one does not satisfy the postcondition of the other.\n- **QuickSelect partition** — the loop returns a position; the postcondition is that the element at that position is the k-th smallest. Off by one in the partition invariant silently breaks it.\n- **DP with reconstruction** — the table tells you the optimum value; reconstructing the optimum path needs separate invariants on the choice array.\n\nIn every case: **write the postcondition first; write the loop invariant second; check that the second implies the first. If not, you are missing a pass, a check, or an auxiliary state.**\n\n## Canonical example — binary search for the leftmost match\n\nMost \"I know binary search\" implementations are written for \"find any match.\" The trap is the postcondition.\n\n**Problem.** Given a sorted array with duplicates, return the index of the **leftmost** occurrence of `target`, or `-1`.\n\n### Without the protocol — returns any match\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  let lo = 0, hi = a.length - 1;\n  while (lo \u003C= hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] === target) return mid;       \u002F\u002F returns ANY occurrence\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid - 1;\n  }\n  return -1;\n}\n\u002F\u002F leftmost([1,2,2,2,3], 2) → may return 2, not 1\n```\n\nThe loop invariant (\"target lies in `a[lo..hi]` if anywhere\") is satisfied. But the postcondition (\"returned index is the *smallest* `i` with `a[i] === target`\") is strictly stronger. The loop body's early return abandons the search before reaching the leftmost.\n\n### With the protocol — contract-driven leftmost\n\n```ts\nfunction leftmost(a: number[], target: number): number {\n  \u002F\u002F contract:\n  \u002F\u002F   pre:  a is sorted ascending\n  \u002F\u002F   post: returns smallest i with a[i] === target, or -1 if absent\n  let lo = 0, hi = a.length;                 \u002F\u002F half-open [lo, hi)\n  \u002F\u002F inv: every index \u003C lo has a[i] \u003C target; every index ≥ hi has a[i] > target OR is past leftmost match\n  \u002F\u002F term: hi - lo strictly halves each iteration\n  while (lo \u003C hi) {\n    const mid = (lo + hi) >> 1;\n    if (a[mid] \u003C target) lo = mid + 1; else hi = mid;\n  }\n  \u002F\u002F exit: lo === hi, and by invariant lo is the leftmost index where a[lo] >= target\n  return lo \u003C a.length && a[lo] === target ? lo : -1;\n}\n```\n\nSame loop shape. The difference is the contract was written first — and the loop body was chosen to maintain an invariant that *implies* the postcondition.\n\n## Common invariant patterns to reach for\n\n| Loop \u002F algorithm shape | Canonical invariant | Termination |\n|---|---|---|\n| Linear scan accumulating | `acc = f(a[0..i))` at top | `i` increases by 1, bounded by `n` |\n| Two-pointer (sorted) | `target (if any) lies in a[lo..hi]` | `hi − lo` strictly decreases |\n| Binary search | `target (if present) ∈ a[lo..hi]` and `a[lo..hi]` non-empty | `hi − lo` strictly halves |\n| Sliding window | window `[l..r)` satisfies the constraint; answer ≥ best so far | `r` advances at least once per outer iter |\n| BFS | every node at distance \u003C d has been popped; queue contains some at distance d | strict node count decrease per pop |\n| DFS \u002F recursion on tree | result for subtree rooted at v = combine(children results) | depth (or remaining nodes) strictly decreases |\n| Divide and conquer | result on `a[lo..hi]` = combine(results on the two halves) | `hi − lo` strictly halves |\n| Greedy with priority queue | extracted item is globally optimal for the remaining problem | heap size strictly decreases per extract |\n| Union-Find op | `find(x)` always returns the canonical root of x's component | tree height bounded by O(log n) (with rank) |\n| In-place partition | `a[0..i)` \u003C pivot; `a[i..j)` ≥ pivot; `a[j..n)` unseen | `n − j` strictly decreases |\n\n## Edge case table — defaults to consider\n\n| Input shape | Cases to check |\n|---|---|\n| Array \u002F list | empty, singleton, all-equal, sorted, reversed, with duplicates |\n| String | empty, single char, all whitespace, unicode (surrogates, combining), bytes vs code points |\n| Integer | 0, 1, −1, MIN, MAX, MAX − 1, near overflow in arithmetic, division by 0 |\n| Float | 0.0, −0.0, NaN, ±Inf, denormal, exact comparison should be ε-based |\n| Map \u002F dict | empty, missing key (default vs error), key collision semantics |\n| Tree \u002F graph | empty, single node, cycle (if undirected), self-loop, multigraph, disconnected |\n| Stream \u002F iterator | empty, infinite, single yield, exception mid-iteration |\n| Time \u002F date | DST transition, leap second\u002Fday, timezone offset, epoch boundary |\n| Concurrent | empty contention, single thread, max contention, cancellation mid-op |\n\n## Output discipline\n\nCode you emit must:\n\n- Have one comment per loop stating the invariant (use `\u002F\u002F inv:` or `# inv:`).\n- Have one comment per recursion stating the base case and measure.\n- Handle every edge case you listed in step 5, or explicitly delegate (\"throws on empty — caller responsibility\").\n- Assert preconditions at function entry when the language supports it cheaply.\n- Use types (sum types, newtypes, non-empty, non-null) over runtime checks where the language allows.\n\n## When to escalate or redirect\n\n- The function is performance-critical and you have not picked the algorithm — go back to **`lemmaly`** first; pick the algorithm, then state its invariants here.\n- The technique is mathematical (probabilistic, FFT, geometry) — load **`mathguard`**; invariants for approximate algorithms include ε-bounds, not equality.\n- The code is concurrent — invariants must account for interleaving; explicitly state \"single-threaded only\" if that is the assumption.\n\n## Rationalizations to watch for\n\n| Excuse | Reality |\n| --- | --- |\n| \"I know this algorithm — single pass, done.\" | Knowing the loop ≠ knowing the contract. The trap usually lives in the postcondition the loop does not enforce. |\n| \"I traced it in my head, it works.\" | Mental tracing skips edge cases. Write the invariant; check it implies the postcondition. |\n| \"Edge cases are obvious.\" | Then write them down in 30 seconds. If they are obvious, the table is cheap. If they are not, the table just saved you. |\n| \"Tests will catch it.\" | Tests catch the examples you thought of. The trap is the example you did not. Postconditions catch all examples. |\n| \"The postcondition is implied.\" | If it were, the natural loop invariant would equal it. When they differ (Boyer–Moore, leftmost search, QuickSelect), you need a second pass, an extra check, or auxiliary state. |\n| \"Adding a verification pass feels redundant.\" | Boyer–Moore voting + verification is still O(n). \"Feels redundant\" is the rationalization that ships the bug. |\n\n## Red flags — STOP and write the invariant first\n\n- About to write `while (...)` without having stated what is true on entry.\n- About to write `if (i === n − 1)` or `if (i === n)` — boundary suspicious, restate the invariant.\n- About to recurse without naming the base case in this message.\n- About to write `\u002F\u002F TODO: handle empty` — handle it now or change the type so empty is impossible.\n- About to use `==` on floats.\n- About to compare across signed\u002Funsigned or across types where overflow rolls.\n- About to silently swallow an error in the middle of a loop (\"just continue\").\n- Tests pass but you did not actually state what the function guarantees.\n- \"It works on the examples I tried.\"\n\n## Verification checklist\n\nBefore claiming the function is correct:\n\n- [ ] Every loop has a one-line `\u002F\u002F inv:` comment in code.\n- [ ] Every loop has a termination argument written down (in comment or PR description).\n- [ ] Every recursion names its base case and measure in code.\n- [ ] The function's postcondition is written and is implied by the exit state of the last loop.\n- [ ] Every applicable edge case from the table has a test or an explicit \"delegated to caller\" note.\n- [ ] At least one test exercises each non-trivial boundary (empty, singleton, max, off-by-one).\n- [ ] Illegal states the function rejects are either unrepresentable in the type, or asserted at entry.\n- [ ] For approximate\u002Frandomized algorithms (escalated to mathguard): ε-bounds are part of the postcondition, not equality.\n\nCannot check every box? The code is example-correct, not behavior-correct. Either fill the gap or downgrade the function's claimed contract.\n\n## Limitations\n\n- **Not an automated prover.** invariant-guard requires the author to *write* invariants; it does not mechanically check them. Pair with property-based tests for stronger evidence.\n- **Concurrency is out of scope by default.** Stated invariants assume single-threaded execution unless explicitly extended; multi-threaded reasoning needs additional happens-before \u002F linearizability arguments.\n- **Float and overflow edge cases are language-specific.** The edge-case table is a checklist, not a substitute for understanding your language's numeric semantics.\n- **Will slow down trivial code.** For one-liners that obviously cannot fail, the protocol is overhead; reserve it for non-trivial loops, recursion, and in-place mutation.\n- **Documentation is the only enforcement.** If the author skips writing the invariants, this skill cannot detect that — pair with code review or a PR template that asks for the contract.\n\n## The thesis, in one line\n\n> **Tests verify examples. Invariants verify behavior. AI assistants ship example-correct, behavior-wrong code by default. invariant-guard makes them reason about behavior first.**\n\n## Related Skills\n\n- `lemmaly` — algorithm choice must be settled before invariants; load lemmaly first if the algorithm family is unclear.\n- `mathguard` — ε-bounded postconditions for approximate \u002F randomized algorithms.\n- `complexity-cuts` — if 3+ optimization transformations have failed tests, the bug is a missing contract, not a missing optimization — escalate here.\n",{"name":5,"risk":24,"tags":25,"tools":32,"author":38,"source":39,"license":15,"date_added":40,"description":7,"source_repo":41,"source_type":39,"license_source":42},"safe",[26,27,28,29,30,31],"algorithms","correctness","loop-invariants","contracts","edge-cases","verification",[33,34,35,36,37],"claude-code","antigravity","cursor","gemini-cli","codex-cli","morsechimwai","community","2026-05-26","morsechimwai\u002Flemmaly","https:\u002F\u002Fgithub.com\u002Fmorsechimwai\u002Flemmaly\u002Fblob\u002Fmain\u002FLICENSE","main","835716bfbede9677a779d77bfd04befb81c069ac","skills\u002Fantigravity__invariant-guard","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI","https:\u002F\u002Fgithub.com\u002Fharesh-sai06","https:\u002F\u002Fharesh-sainaath.live\u002F","I am a Student pursuing Artificial Intelligence and Machine Learning at Sri Krishna College of Technology,Coimbatore.","2026-06-13 22:42:28",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add haresh-sai06\u002FSapSynk-AI --skill invariant-guard",{"tool":57,"command":58},"bunx","bunx skills add haresh-sai06\u002FSapSynk-AI --skill invariant-guard",{"tool":60,"command":61},"pnpm","pnpm dlx skills add haresh-sai06\u002FSapSynk-AI --skill invariant-guard","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fantigravity__invariant-guard\u002FSKILL.md",true,[],[66,75,82,89,96,103],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":74},"01M77GQ5PRFQMV3QBDAQPCSXJB","youtube-full","Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private\u002Fage-restricted videos.","MIT","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__youtube-full-2\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":74},"01M77GPXXAB3Y8ZNG919MD4703","x-twitter-growth","X\u002FTwitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X\u002FTwitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__x-twitter-growth-2\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":74},"01M77GPSS7AFYH90Y5S6XHRXZW","write-a-skill","Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__write-a-skill-2\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":74},"01M77GPKB6HJS2X5XK03649C6R","workflow-builder","Design and write deterministic multi-agent workflow scripts (.js files in .claude\u002Fworkflows\u002F) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__workflow-builder-2\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":74},"01M77GP31EFXE1KS38XBZ1J9MN","webinar-marketing","When the user wants to plan, promote, run, or improve a webinar or virtual event to generate and convert demand. Use when the user mentions 'webinar,' 'virtual event,' 'online event,' 'live demo,' 'virtual summit,' 'workshop,' 'masterclass,' 'fireside chat,' 'roundtable,' 'registration funnel,' 'show-up rate,' 'attendance rate,' 'webinar promotion,' 'webinar follow-up,' or 'on-demand webinar.' Also use when they have a webinar that isn't converting — low registrations, low show-up, or attendees who don't buy — and want to diagnose and fix it. Covers the full funnel: registration, promotion, show-up, live engagement, live-to-close, and post-event nurture. Distinct from launch-strategy (full product launches) and email-sequence (lifecycle nurture) — this is the end-to-end webinar\u002Fevent motion. NOT for in-person field events logistics, and NOT for generic lifecycle email (use email-sequence).","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__webinar-marketing-2\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":70,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":74},"01M77GNNA22HWXX6CEQQ3JY2YB","vpe-advisor","VP of Engineering advisory for startups: delivery throughput (DORA 4 metrics + bottleneck identification), engineering hiring funnel (sourcing → screen → onsite → offer conversion + time-to-fill + pipeline gap), engineering team structure (squad\u002Ftribe\u002Fchapter design + tech-lead manager-trigger thresholds), and production discipline (on-call, deployment cadence, postmortem culture). Use when sprint velocity is dropping, eng hiring is broken, team structure is unclear, or deciding when to add a tech-lead manager. NOT a CTO skill (which owns architecture) — VPE owns delivery operations and how the team ships.","https:\u002F\u002Fgithub.com\u002Fharesh-sai06\u002FSapSynk-AI\u002Fblob\u002Fmain\u002Fskills\u002Fclaude__vpe-advisor-2\u002FSKILL.md",[],[]]