loopeng-gherkin

Convert TLC counterexample traces into Gherkin acceptance scenarios.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? TLA+ model checking produces counterexample traces that are hard to act on directly. This Skill mechanically converts those traces into Gherkin .feature files so design-level bugs become executable acceptance specifications that bridge into implementation testing. ## Core Features & Use Cases - Counterexample Conversion: Transform TLC error traces into Gherkin Scenarios where the initial state becomes Given, each action becomes When, and changed variables become Then becomes ... assertions. - Acceptance Scenario Authoring: Once the design stabilizes, add positive EARS-based acceptance scenarios to the .feature file and wire them into implementation acceptance tests. - Runner Wiring Guidance: Reference documentation covers language-native Cucumber runners (pytest-bdd, cucumber-js, godog, and others) plus a C conversion path for freestanding environments, with green/red verification of the wiring. - Use Case: After loopeng-modelcheck finds an invariant violation, run the inner loop to generate a .feature capturing the failing behavior, fix the design until the counterexample disappears, then hand the scenarios to test-extract for ledger registration before writing implementation tests. ## Quick Start Convert the TLC counterexample trace from my last model check into a Gherkin feature file and add positive acceptance scenarios for the stabilized design.

Frequently Asked Questions about loopeng-gherkin

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

FAQPage Schema
How do I convert a TLC counterexample trace into a Gherkin feature file?

Run the inner loop command with the spec name, which invokes trace_to_gherkin.py to mechanically convert the TLC error trace. The initial state becomes Given steps, each action becomes a When step, and changed variables become Then becomes assertions.

What test runners can execute generated Gherkin feature files?

Use language-native Cucumber OSS runners: pytest-bdd or behave for Python, cucumber-js for JS/TS, godog for Go, cucumber-rs for Rust, and cucumber-jvm for Java/Kotlin. You write one thin glue layer mapping When actions to implementation calls and Then steps to state comparisons.

Can I run Gherkin acceptance tests in freestanding C without libc?

Yes, but no off-the-shelf runner exists for that environment. Use feature_to_c.py with a project-specific JSON mapping file to convert machine-format features into C CHECK sequences, then link the generated code into your own test harness as a single translation unit.

Should I hand-edit the generated .feature files?

No. Generated features must never be hand-edited; fix the source spec or EARS requirements and regenerate instead. The generators also only accept machine-format output from trace_to_gherkin.py, not hand-written prose scenarios.

What happens if I skip registering scenarios in the test design ledger?

Writing implementation tests without transferring scenarios to test-extract is blocked by the test-design-extract-gate hook. Each scenario must become one T-ID row in the test design ledger with the feature file recorded as its source.