loopeng-formalize

Converts extracted requirements into EARS notation, state models, and TLA+ specifications.

Updated Jun 24, 2026
One-click install
npx skills add https://github.com/Hakkadaikon/hymme --skill loopeng-formalize-hakkadaikon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: loopeng-formalize
Source: https://github.com/Hakkadaikon/hymme/tree/main/skills/loopeng-formalize
Command: npx skills add https://github.com/Hakkadaikon/hymme --skill loopeng-formalize-hakkadaikon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Natural-language requirements are ambiguous and cannot be machine-checked. This Skill structures extracted requirements into EARS-notation statements and a state/domain model, then lowers them into a TLA+ specification (<Name>.tla / <Name>.cfg) and a Gherkin skeleton (<Name>.feature) ready for model checking. ## Core Features & Use Cases - EARS Structuring: Rewrites each requirement into one of the five EARS patterns (ubiquitous, event, state, unwanted, optional), with a reference of compound patterns for multi-condition, role-based, priority, and quantified NFR cases. - State/Domain Modeling: Derives state variables, types, initial state, and invariants, and records which regions were deliberately abstracted away so they are verified elsewhere. - TLA+ Scaffolding: Generates <Name>.tla and <Name>.feature from templates via the loop-outer toolchain, mapping each EARS clause to one Next disjunct and ubiquitous clauses to invariants, with a traceability matrix back to the requirement ledger. - Use Case: After loopeng-extract closes a requirements ledger for a payment flow, run this Skill to produce EARS statements, a state model, and a TLA+ spec that loopeng-modelcheck can verify with TLC. ## Quick Start Formalize the extracted requirements in tasks/loopeng/Payment.extract.md into EARS statements and generate the TLA+ spec and Gherkin skeleton.

Frequently Asked Questions about loopeng-formalize

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

FAQPage Schema
How do I convert natural-language requirements into EARS notation?

Rewrite each requirement as a single sentence using one of the five EARS patterns: ubiquitous, event-driven (WHEN), state-driven (WHILE), unwanted behavior (IF/THEN), or optional (WHERE). Compound cases like multi-condition triggers, role-based permissions, and quantified NFRs use the patterns in the ears-patterns reference.

How do I write a TLA+ spec from structured requirements?

Map state variables to VARIABLES with TypeOK type constraints, the initial state to Init, and each EARS event/state/unwanted clause to one disjunct in Next. Ubiquitous clauses and 'shall never' statements become invariants, and the .cfg file declares INIT, NEXT, and INVARIANT for TLC.

What is required before formalizing requirements into TLA+?

The loopeng-extract ledger at tasks/loopeng/<Name>.extract.md must be complete, with every requirement ID checked off and no gaps. If the ledger is missing or unfinished, return to the extraction step before formalizing.

Why should abstracted-away details be recorded during state modeling?

Details dropped during modeling, such as internal value representations or field-level validation, fall outside TLC's checking scope by design. Recording them in the ledger ensures another verification layer covers them instead of disappearing unverified.

Can I hand-edit the generated TLA+ or Gherkin files?

No. Generated .tla and .feature files must not diverge from their source EARS statements and state model. Fix the source and regenerate so the specification and its requirements stay synchronized.