Skip to content
Skills Library
Programming · Analysis

spec-weaver

/spec-weaver

[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.

Repository
spec-weaver ↗
Licence
MIT
Last repository change
03.11.2026

Assessment and security

100/ 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.
Content35 / 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
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.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

[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.

Original author description

[WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms using TLA+, PlusCal, or automated state-space exploration before implementation. [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks, consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical. [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.

How it works

  1. 1. When to Activate
  2. 2. Mathematical Formalization Runbook
  3. 3. Reference Files
Original SKILL.md headings · 85 lines, 406 words
SKILL.md preview
---
name: spec-weaver
description: >-
  [WHAT IT DOES]: Formally specifies and mathematically proves concurrent, distributed, and state-machine algorithms
  using TLA+, PlusCal, or automated state-space exploration before implementation.
  [WHEN TO USE]: Use when the user designs financial ledgers, concurrent transaction logic, distributed locks,
  consensus protocols, or complex asynchronous workflows where race conditions, deadlocks, or state corruption are critical.
  [WHEN NOT TO USE]: Do NOT use for basic CRUD operations, static web forms, or synchronous single-threaded UI rendering.
---

# Spec Weaver: Mathematical Formal Verification Engine

```
  +--------------------------------------------------------------------------+
  |                                SPEC WEAVER                               |
  |             Mathematical Invariant & State-Space Proof Engine            |
  +--------------------------------------------------------------------------+
       |                                                    |
       v                                                    v
  [State Invariants]                                [System Transitions]
   - Type Invariants                                 - Next State Relations
   - Safety: [](NoNegativeBalance)                   - Message Dropping
   - Liveness: <>(TerminalState)                     - Concurrency Interleaving
       |                                                    |
       +-------------------------+--------------------------+
                                 |
                                 v
                     [BFS Model Checker Loop]
                     - Cycle Detection
                     - Invariant Guard Evaluation
                     - State-Space Hash Deduplication
                                 |
                +----------------+----------------+
                |                                 |
          [Passed (100%)]                   [Counterexample]
                v                                 v
      [Generate Code Scaffold]         [Emit Minimal Error Trace]
      - Pre/Post Condition Guards      - Pinpoint Interleaving Bug
      - Mathematical Certificate       - Auto-Propose Invariant Fix
```

---

## 1. When to Activate

Trigger `spec-weaver` whenever the user's task involves:
- **Financial & Ledger Systems:** Account balances, currency transfers, multi-party escrow, double-spend prevention.
- **Distributed Concurrency:** Two-phase commits (2PC), leader elections (Raft/Paxos variants), distributed mutexes.
- **Complex Asynchronous Lifecycles:** Stateful job runners, saga orchestrators, retry-with-cancellation pipelines.
- **Elusive Heisenbugs:** Flaky race conditions or deadlock bug reports that are difficult to reproduce with standard unit tests.

---

## 2. Mathematical Formalization Runbook

### Step 1: Elicit Invariants
Before generating code or specs, list the core invariants:
1. **Safety Properties ($\square P$):** "Bad things never happen."
   * *Example:* `\A a \in Accounts : balance[a] >= 0`
   * *Example:* `Cardinality(ActiveLeaders) <= 1`
2. **Liveness Properties ($\diamondsuit P$):** "Good things eventually happen."
   * *Example:* `RequestIssued ~> RequestResolved`
3. **Type Correctness ($TypeOK$):** State bounds, enum domains, set memberships.

### Step 2: Run Automated State-Space Exploration
Execute the Python verification engine to prove the algorithm across all possible interleaved transitions:
```bash
python scripts/verify_invariants.py --demo
```
Or define custom states in Python and run:
```python
from scripts.verify_invariants import StateSpaceVerifier

verifier = StateSpaceVerifier(initial_state={"status": "IDLE", "lock": False})
verifier.add_safety_invariant("ValidStatus", lambda s: s["status"] in {"IDLE", "RUNNING", "DONE"})
verifier.add_transition("Start", lambda s: [{"status": "RUNNING", "lock": True}] if not s["lock"] else [])
is_valid, err, trace = verifier.verify(check_deadlocks=True)
```

### Step 3: Handle Counterexamples
If the model checker finds an invariant violation:
1. Read the minimal state trace emitted by `print_counterexample()`.
2. Locate the specific transition where mutual exclusion was lost or a race occurred.
3. Propose a refined guard (e.g. Compare-And-Swap, atomic transaction boundary, or sequence token).

### Step 4: Export Verified Production Code
Translate the verified transitions into the target language (Go, Rust, TypeScript, Python) with runtime invariant assertion checks embedded directly into the code.

---

## 3. Reference Files
- [verify_invariants.py](./scripts/verify_invariants.py): The industrial-grade BFS state-space model checker.
- [model_template.tla](./templates/model_template.tla): Standard TLA+/PlusCal formal model template.
Files in this package (4)
  • .gitignore 1 KB
  • LICENSE 1 KB
  • README.md 4 KB
  • SKILL.md 5 KB

Versions

The database has no other skills named spec-weaver.

Database snapshot: 13.11.2026 · package version 67c01ec72407 (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

  • 100tla-model
    Models concurrent and distributed designs in TLA+ or PlusCal and checks them with the TLC model checker. Use when asked to write, review, or debug a TLA+ spec, .tla/.cfg files, or TLC output, or to model-check or formally verify a protocol, lock, lease, consensus, replication,…
  • 100tla
    Formally verify a capability's invariants with TLA+ and TLC, and record the result as metamodel Evidence. Use when the constitution's formal verification assessment flags a component (concurrency, distributed state, financial transactions, safety-critical logic, complex state machines, protocols).
  • 100tlaplus-spec-generator
    Automatically generate TLA+ specifications from source code (C/C++, Python) for formal verification of distributed systems. Use when users need to: (1) Generate TLA+ specs from program implementations, (2) Model distributed systems, consensus protocols, or concurrent algorithms,…
  • 100program-to-tlaplus-spec-generator
    Automatically generate TLA+ specifications from program code, repositories, or system implementations. Use when asked to generate TLA+ spec, create TLA+ specification from code, convert program to TLA+, formalize system in TLA+, extract TLA+ model from code, or when working with…
  • 100slo-tla
    Use this skill when /slo-architect has set tla_required=true, or when the user asks to "verify the design", "model check", "prove this is correct", "add TLA+ to this plan", or whenever a design involves concurrent actors, distributed state, ordering guarantees, resource…
  • 90tlaplus
    Use to model-check real code or a design with TLA+ and TLC. Model retries, locks, async flows, protocols or state machines as written, check invariants over every interleaving, and reproduce any counterexample trace as a failing test. Dispatched by /engineer.harden for…

Feedback and reports

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