| name | effortless-rulespeak |
| description | Use when generating plain-English RuleSpeak documentation from an effortless-rulebook.json — declarative business rules, vocabulary, fact types, definitional rules (DR-n), and traceability back to formulas. Installs `rulebook-to-rulespeak` and emits `rulespeak/rulespeak.md` and `rulespeak/rulespeak.html` on every build.
**Default whenever a rulebook is created.** Any time an agent authors `effortless-rulebook/effortless-rulebook.json` — "write a rulebook for …", bootstrap, init, demo app, or hand-edit from scratch — install this transpiler and run `effortless build` so the sibling `rulespeak/` folder exists before handing back. Do not wait for the user to ask.
Triggers: "generate rulespeak", "rulebook-to-rulespeak", "english rules document", "plain language rules", "business rules doc from rulebook", "rulespeak.md", "create a rulebook", "write a rulebook for".
**Scope (load gate):** Effortless projects with a rulebook hub, OR any task that creates a new rulebook (load alongside effortless-schema). Does not require Airtable. For interactive in-app field provenance, use effortless-explainer-dag on demand instead.
|
| audience | customer |
Effortless RuleSpeak — rulebook → plain English
rulebook-to-rulespeak renders effortless-rulebook.json into RuleSpeak —
a declarative, business-readable document of the same rules the formulas encode.
Every calculated, lookup, and aggregation field becomes a definitional rule;
relationships become fact types; tables become vocabulary.
This is the default human-readable sibling of every new rulebook — not an
optional add-on. If you just wrote effortless-rulebook.json, you also wire
RuleSpeak before declaring the task done.
For clickable in-app field exploration (hover cards, DAG pages), load
effortless-explainer-dag separately when the user asks — that is optional,
not part of the standard rulebook-creation path.
Default on rulebook creation (do this every time)
Whenever you create or first populate a rulebook hub — regardless of whether
Postgres, an app, or Airtable comes next:
- Install (once per project, skip if
effortless.json already has
rulebooktorulespeak):
mkdir -p rulespeak
cd rulespeak
effortless -install rulebook-to-rulespeak -i ../effortless-rulebook/effortless-rulebook.json
cd ..
- Build from project root:
effortless build
- Verify both outputs exist:
rulespeak/rulespeak.html ← open in browser (primary human deliverable)
rulespeak/rulespeak.md ← same content, markdown
- Tell the user where to read the rules in English (
rulespeak/rulespeak.html).
Do not skip this because the user only asked for "a rulebook" — the
RuleSpeak sibling is how humans sanity-check what the JSON encodes. Only skip
if the user explicitly says they do not want RuleSpeak.
Parent skills that must invoke this block: effortless-init (Step 3.5),
effortless-bootstrap (after Step 10), effortless-demo-app (bootstrap
step 7), effortless-setup-postgres (after rulebook is in place).
Install (reference)
Expected ProjectTranspilers entry:
{
"Name": "rulebooktorulespeak",
"RelativePath": "/rulespeak",
"CommandLine": "rulebook-to-rulespeak -i ../effortless-rulebook/effortless-rulebook.json",
"IsDisabled": false
}
Build
effortless build
./start.sh build
Output (regenerated on every build):
| File | Purpose |
|---|
rulespeak/rulespeak.html | Browser-readable RuleSpeak (prefer this when handing off) |
rulespeak/rulespeak.md | Same content in markdown |
What the document contains
| Section | Content |
|---|
| Business Vocabulary | One term per table + derived fields |
| Fact Types | Cardinality from relationships |
| Operative Rules | Structural must / must not / should (from schema + optional Constraints table) |
| Definitional Rules | DR-n rows — one per calculated/lookup/aggregation field |
| Traceability to Schema | Each derived field mapped back to its formula (the hub SSoT) |
After rulebook edits
RuleSpeak is an output spoke — it regenerates on every effortless build.
After any hub change, rebuild; do not hand-edit rulespeak/*.
Optional: semantic obligations
For deontic rules beyond schema flags (nullable:false), add a Constraints
table to the rulebook. Each row points at a boolean calculated field on an entity
and annotates it with MustBeTrue / MustNotBeTrue / ShouldBeTrue. See the
rulebook-to-rulespeak tool README (UsingRulespeakConstraints.md) for the full
column contract.
See also
effortless-explainer-dag — on-demand in-app DAG + hover RuleSpeak (not default)effortless-pipeline — transpiler install paths and build ordereffortless-schema — load before authoring the rulebook JSONeffortless-init — Step 3.5 wires RuleSpeak after the hub exists
