empirical-system-invariants

Validates per-cycle data contracts in pipelines and fails builds on NULL fields.

Updated Sep 11, 2026
One-click install
npx skills add https://github.com/manusabbath-arch/hermes-skills --skill empirical-system-invariants-manusabbath-arch
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: empirical-system-invariants
Source: https://github.com/manusabbath-arch/hermes-skills/tree/main/skills/empirical-system-invariants
Command: npx skills add https://github.com/manusabbath-arch/hermes-skills --skill empirical-system-invariants-manusabbath-arch

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Data pipelines silently produce NULL fields, phantom wiring, and degenerate rows that no one detects until a lucky debugging session. This Skill turns "does it work?" into a mechanical answer by enforcing per-cycle data contracts that fail loudly with the exact broken link. ## Core Features & Use Cases - Per-cycle data contracts: Five contract types (ingest, model, signal enrichment, guard-to-order, shadow ledger) verify each pipeline stage populated what it promised, with explicit NULL-vs-zero semantics per field. - Fail-high guard script: scripts/invariant_guard.py runs contract checks against a SQLite database and exits 0 (all green), 1 (business RED), or 2 (schema/data error), never swallowing exceptions. - Contract template: templates/data-contracts.md guides writing acceptance queries before code, including boundary-twin tests and fresh-connection DB reads. - Use Case: A trading bot accumulates edge_elo values that are always NULL because the enrichment code was never written. Declare a not_null_ratio contract, run the guard each cycle via cron, and get a RED status naming the exact stage and field until the model populates it. ## Quick Start Ask the agent to audit your pipeline by declaring a JSON data contract for each stage and running the invariant guard script against your production database to report any RED links.

Frequently Asked Questions about empirical-system-invariants

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect NULL fields in a data pipeline automatically?

Declare a JSON contract per pipeline stage specifying the field, a not_null_ratio check, and a production query, then run the invariant_guard.py script against your SQLite database. It exits with code 1 and names the exact stage and field when the populated ratio falls below your threshold.

How to write data contracts for ETL pipeline validation?

Write the acceptance query before the code, asserting plausible values in post-deploy rows rather than just row existence. The templates/data-contracts.md file provides a table format covering source stage, consumer, promised field, condition, production query, and NULL-versus-zero semantics.

Does the invariant guard script require external Python packages?

No, invariant_guard.py uses only the Python standard library (argparse, json, sqlite3, os, sys). It runs on Linux, macOS, and Windows without installing any dependencies.

Why does my database check pass when the data is actually missing?

Reading through a connection pool can show the pool's own uncommitted transaction and hide the bug. The guard opens a fresh SQLite connection for every check so it sees only committed production state.

When should a monitoring check become a pre-deploy gate?

Monitor in production for hours first, since reconnects can make everything look healthy for minutes. Establish your own baseline per channel, then promote the check to a deploy gate behind a kill-switch flag so it can be disabled while stabilizing.