business-requirements

Business Requirements

The harness checks the finished app against a list of business requirements and gives a ship / do-not-ship decision. Those requirements live in the app repo as a single JSON file:

_doc/business-requirements.json

It is a JSON array; each entry is one requirement:

{
  "id": "no-checkout-when-closed",
  "excerpt": "No buying from a closed store.",
  "description": "A customer cannot check out when the selected outlet is closed.",
  "type": "explicit",
  "severity": "critical"
}

Field rules:

• id — stable kebab-case slug. Reuse the existing id when editing a requirement (never renumber). Only mint a new kebab-case id for a genuinely new requirement.
• excerpt — a tiny glance-line, ideally under ~8 words, clearly shorter than description.
• description — the requirement in explain-like-I'm-five language: short sentences, everyday words, as if explaining to someone with zero technical background. Describe what a person or the business experiences — never code, functions, APIs, endpoints, databases, schemas, tables, or frameworks. If you catch yourself naming a technical thing, rephrase it as what the user or business experiences.
  • Good: "A customer cannot check out when the selected outlet is closed."
  • Good: "Loyalty points are only awarded after an order is completed, never when it is cancelled."
  • Bad: "The /checkout endpoint validates outlet.is_open before creating the order."
• type — "explicit" when the user asked for it directly, "hidden" when it is implied by the product category but not stated (e.g. preventing double rewards, blocking orders to a closed outlet).
• severity — "critical", "high", "medium", or "low", by business impact if unmet. Only critical requirements block the ship gate; the rest surface as warnings.

How to edit (MANDATORY steps)

Requirements are normally auto-derived from _doc/product-overview.md. To make a hand edit stick — so the next auto-derivation does not overwrite it — you MUST do BOTH: