Skip to content
Skills Library
Programming · Building & coding

invariant-first-code

/invariant-first-code

Invariant-first engineering for code with security, correctness, integrity, or availability claims: auth and permissions, persistence, transactions, migrations, concurrency, APIs, secrets, lifecycle, and release/supply chain. Use whenever you design or review a feature that must not be bypassed, must not lose or corrupt data, must not double-apply an operation, or must fail closed. Turn every claim into an explicit invariant, enforce it at one choke point, and prove the enforcement can actually fail.

Licence
MIT
Last repository change
08.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Invariant-first engineering for code with security, correctness, integrity, or availability claims: auth and permissions, persistence, transactions, migrations, concurrency, APIs, secrets, lifecycle, and release/supply chain. Use whenever you design or review a feature that must not be bypassed, must not lose or corrupt data, must not double-apply an operation, or must fail closed. Turn every claim into an explicit invariant, enforce it at one choke point, and prove the enforcement can actually fail.

Original author description

Invariant-first engineering for code with security, correctness, integrity, or availability claims: auth and permissions, persistence, transactions, migrations, concurrency, APIs, secrets, lifecycle, and release/supply chain. Use whenever you design or review a feature that must not be bypassed, must not lose or corrupt data, must not double-apply an operation, or must fail closed. Turn every claim into an explicit invariant, enforce it at one choke point, and prove the enforcement can actually fail.

How it works

  1. The core rule
  2. Invariant map
  3. Design for fail-closed
  4. Authorization invariants
  5. Data and transaction invariants
  6. Concurrency invariants
  7. Interfaces and errors
  8. Lifecycle and secrets
  9. Platform contracts
  10. Build and supply chain
Original SKILL.md headings · 192 lines, 1,398 words
SKILL.md preview
---
name: invariant-first-code
description: >
  Invariant-first engineering for code with security, correctness, integrity,
  or availability claims: auth and permissions, persistence, transactions,
  migrations, concurrency, APIs, secrets, lifecycle, and release/supply
  chain. Use whenever you design or review a feature that must not be
  bypassed, must not lose or corrupt data, must not double-apply an
  operation, or must fail closed. Turn every claim into an explicit invariant,
  enforce it at one choke point, and prove the enforcement can actually fail.
---

# Invariant-First Code

Code is a set of invariants that someone believes hold. Make them explicit,
enforce them at a choke point, and test the enforcement adversarially. A guard
that exists on one path is not a property of the system.

## The core rule

For every invariant, answer:

1. **Statement** — what must always be true, in falsifiable terms.
2. **Enforcement point** — the single place that prevents violation.
3. **Failure mode** — what happens when enforcement is missing or errors:
   deny, abort, roll back, or degrade safely. Never allow-by-default.
4. **Evidence** — the negative test, analysis, or proof that shows a
   violation attempt fails.
5. **Scope** — platforms, versions, actors, and paths covered.

If the invariant has no enforcement point or no violation test, it is a wish.

## Invariant map

Keep a map next to the design or in `references/invariant-template.md`:

| ID | Invariant | Enforcement point | Failure mode | Evidence | Scope |
| --- | --- | --- | --- | --- | --- |
| I-01 | No session writes without a valid capability | `authorize_write()` | deny | T-04..T-09 | all write paths |

Add invariants for:

- **Authorization:** deny by default; no path bypasses the check; role-less,
  expired, neighboring, and admin actors are distinct cases.
- **Data integrity:** constraints, transactions, idempotency, migration
  ordering, backup/restore, crash recovery.
- **Concurrency:** one writer per resource, leases and fencing tokens,
  retries, duplicate delivery, stale workers.
- **Lifecycle:** initialization before use, cleanup on every exit path,
  secret rotation, zeroization of sensitive buffers.
- **Contracts:** typed errors, no partial writes, no secret leakage, stable
  behavior at boundaries.
- **Supply chain:** pinned dependencies, provenance, SBOM, reproducible
  builds, no secrets in artifacts.

## Design for fail-closed

- The default is deny. An error, timeout, missing configuration, unknown
  role, or unavailable policy service must not widen access.
- Put the check at the narrowest choke point that every path must cross.
  Do not duplicate policy in handlers; duplicated policy drifts.
- Separate authentication, authorization, and audit. A logging failure must
  not silently disable authorization.
- Treat "not found", "not supported", and "not configured" as distinct
  outcomes; do not collapse them into allow.
- If the platform provides defense in depth, keep your check and label it as
  defense in depth. Do not rely on the platform as the only guard.
- Make bypasses explicit and privileged: migrations, maintenance mode,
  recovery, and admin tools need their own gated path, not an ambient flag.

## Authorization invariants

- Enumerate every entry point: direct calls, prepared statements, nested
  calls, batch operations, imports, admin APIs, background jobs, and
  migrations.
- Test the outsider cases: wrong role, no role, expired session, revoked
  capability, neighboring tenant, object owner, admin without the specific
  grant.
- Test the object-level check, not only the route-level check. A user who can
  reach an endpoint must not automatically reach every object.
- Audit writes go through one channel; test whether the actor can modify or
  delete their own trail.
- Lockout and rate-limit unlock paths are permission-gated too.

## Data and transaction invariants

- Enforce invariants in the database where concurrent writers can violate
  them, not only in application code.
- A refused operation must leave no partial write. Check the side effects
  after every expected failure.
- Make retries idempotent with a stable key; "exactly once" is a protocol
  property, not a wish. Design for at-least-once delivery.
- Migrations run in a defined order, are restartable, and preserve
  constraints. Rerun negative tests on migrated live data.
- Backups are not evidence until a restore has been tested. Record the
  restore drill, not only the backup job.

## Concurrency invariants

- Name the resource, the contention, and the serialization mechanism.
- Prefer database constraints and row locks to application-level check-then-
  act. Check-then-act is a race unless the check and act are atomic.
- Use fencing tokens or monotonic epochs for leases and stale workers. A
  worker that lost its lease must not commit.
- Test duplicate delivery, retry storms, two writers, and a worker paused
  between check and write.
- A lock without a timeout is an availability bug; a timeout without
  correctness is a data bug.

## Interfaces and errors

- Define the error contract: which inputs are rejected, with which code, and
  whether any state changed.
- Do not leak secrets, tokens, internal paths, or stack traces in errors.
- Do not turn an internal failure into a success-shaped empty result.
- Validate at the boundary, then keep the validated representation; do not
  re-parse untrusted input in deeper layers.
- Batch and bulk paths need the same checks as single-item paths.

## Lifecycle and secrets

- Initialize before use; clean up on success, error, cancellation, and
  timeout paths.
- Zero or wipe sensitive buffers where the platform allows it; do not rely on
  garbage collection for secrets.
- Load secrets from the deployment secret store, never from source,
  fixtures, logs, or build artifacts.
- Rotation must invalidate old credentials within the stated window. Test
  the stale-credential case.
- Destructors and cleanup must be idempotent; a failed cleanup must be
  visible, not silent.

## Platform contracts

- Declare supported versions and required privileges. A behavior that depends
  on an unsupported configuration is out of scope, not "works on my machine".
- Test on every supported platform, or state exactly which platform was
  tested and which was not.
- When the platform refuses first, report it honestly as defense in depth.
- Pin the platform behavior you rely on with a test; upgrades can change it.

## Build and supply chain

- Pin dependencies and build inputs; record the lockfile and toolchain.
- Generate an SBOM and provenance for release artifacts.
- Run secret scanning and dependency vulnerability checks in CI.
- Make builds reproducible enough to detect tampering; record the commit,
  builder, and inputs.
- Do not ship debug endpoints, default credentials, or permissive CORS by
  accident.

## Verification

- For each invariant, write the negative test first and verify it fails when
  the enforcement is removed.
- Use static analysis for whole-program properties, dynamic tests for
  behavior, fuzzing for parsers and state machines, and sanitizers for memory
  and undefined behavior. Record which tool covered which invariant.
- Mutation-test critical guards or inject a no-op; a test that cannot fail is
  not evidence.
- Verify the verifier: check the oracle, the fixture, and the assertion, not
  only the exit code.
- Record residual risk: what was not tested, what was out of scope, and what
  remains open.

## Review checklist

- Every security and integrity claim has an invariant ID and an enforcement
  point.
- Every enforcement point is on every path; no ambient bypass.
- Failure is closed, visible, and leaves no partial state.
- Outsider, role-less, expired, and neighboring-object cases are tested.
- Concurrency is enforced atomically, with fencing for stale workers.
- Errors do not leak secrets and do not convert failure into success.
- Cleanup runs on every exit path; secrets are not logged.
- Supported platforms and privileges are stated.
- Supply chain inputs are pinned and scanned.
- The negative test fails when the guard is removed.

## Anti-patterns

1. **Check on one path.** The guard exists in the HTTP handler but not in the
   batch job, import, or migration.
2. **Allow on error.** A policy service timeout becomes "no policy, allow".
3. **Check-then-act.** A race between the permission check and the write.
4. **Partial write on refusal.** The error is correct; the state is not.
5. **Platform as the only guard.** Defense in depth is good; sole defense is
   fragile.
6. **Silent cleanup failure.** The resource leaks and nobody sees it.
7. **Secret in the log.** The error message includes the token or password.
8. **Unfalsifiable test.** The test passes even when the mechanism is removed.
9. **Stale scope.** "Tested" on an unsupported version or configuration.
10. **Supply-chain blind spot.** Dependencies and build inputs are unpinned.

Use `references/review-checklist.md` for a compact review pass. If the
repository includes a standards crosswalk, it lives at
`references/standards-map.md`; the skill itself does not depend on a standard.

Keep the design proportional to the request. Group tests by invariant and
mark the release-blocking ones; do not turn a five-invariant review into a
45-test catalogue. When the platform is not specified, label the chosen
platform as an assumption or ask; do not present invented versions as facts.
Files in this package (6)
  • LICENSE 1 KB
  • README.en.md 4 KB
  • README.md 6 KB
  • SKILL.md 9 KB
  • references/invariant-template.md 2 KB
  • references/review-checklist.md 3 KB

Versions

The database has no other skills named invariant-first-code.

Database snapshot: 13.11.2026 · package version 4956d2a81da0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90universal-invariant-baseline
    Use when invoked to apply an invariant-first, fail-fast, special-case-eliminating baseline. Not for domain models in types: use type-driven. Not for design-by-contract: use contract-driven.
  • 100shared-invariant-backfill
    When the fix tightens an invariant, backfill the historical data that violates it, or the fix remains true only for records from today onward. Use when the fixed check depends on state, and records written before the fix fail the new invariant
  • 100code-comment-style
    Write and tighten code comments so they state the why or the invariant in 1-3 lines. Use when adding comments to code, or when pruning verbose comments in a diff or PR.
  • 100invariant-test
    Derive surface tests from a service's stated invariants (Accepted ADRs, load-bearing doc comments, tech specs), targeting the assertions a codebase's defensive mechanisms (mutexes, transactions, atomic backend ops) cannot satisfy — then write each test and mutation-validate it…
  • 90bec-code-review
    Use when A backend diff, pull request or release change needs read-only review for correctness, concurrency, consistency, security, compatibility and test evidence.
  • 91branch-invariant
    Use when a commit or checkout may have left a repository on a detached HEAD.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.