Context
Adding a scenario is the most common contribution, but the rules for a good one are scattered across docs/DESIGN.md, the scenarios.py docstrings, and the type docstrings. A short guide would lower the barrier: how to pick a meaningful-but-unique value, when to add aliases vs confirm_phrases, the deny-list semantics of forbidden (unlisted = allowed), and how appropriate_flows drives utility.
Acceptance criteria
- A concise guide (e.g.
docs/SCENARIOS.md or a section appended to docs/DESIGN.md) covering: value selection, aliases, forbidden vs appropriate semantics, and registering in ALL_SCENARIOS.
- Uses only synthetic, domain-neutral placeholder examples — no real data.
- States the invariants a scenario must satisfy (unique attribute names/recipient ids; forbidden/appropriate reference real ids).
- Linked from
CONTRIBUTING.md and/or README.md.
Context
Adding a scenario is the most common contribution, but the rules for a good one are scattered across
docs/DESIGN.md, thescenarios.pydocstrings, and the type docstrings. A short guide would lower the barrier: how to pick a meaningful-but-unique value, when to addaliasesvsconfirm_phrases, the deny-list semantics offorbidden(unlisted = allowed), and howappropriate_flowsdrives utility.Acceptance criteria
docs/SCENARIOS.mdor a section appended todocs/DESIGN.md) covering: value selection, aliases, forbidden vs appropriate semantics, and registering inALL_SCENARIOS.CONTRIBUTING.mdand/orREADME.md.