liveBook · Manning

Specification authoring

As explained in Vibe Engineering

The process of defining a system's required behavior, constraints, and acceptance conditions.

A request such as “refunds within 30 days” leaves important behavior unstated: the time boundary, partial refunds, money arithmetic, and rejection reasons. Specification authoring turns that intent into explicit, reviewable conditions that a pipeline can check. A working prototype can help reveal rules, data shapes, and edge cases before the final feature is designed. section 1.5 section 1.4.1

Write examples in a form the project’s verification pipeline can run. Given–When–Then scenarios can capture both successful outcomes and reasons for rejection. The examples are a contract for the failures considered, not proof that every failure has been found. section 1.5 section 1.4.1

Feature: Refund policy
  Rule: Time-bounded, single-order refunds
    Example: Within 30 days is allowed
      Given an order "O1" purchased at 2025-08-01T10:00:00Z
      When a refund of 25.00 USD is requested at 2025-08-28T09:59:00Z
      Then the refund is approved and remaining refundable equals 75.00 USD
 
    Example: After 30 days is rejected
      Given an order "O2" purchased at 2025-08-01T10:00:00Z
      When a refund is requested at 2025-08-31T10:00:01Z
      Then the request is rejected with reason "expired"
 
    Example: Partials must not exceed the original
      Given prior refunds of 90.00 USD on a 100.00 USD order
      When a refund of 20.00 USD is requested
      Then the request is rejected with reason "exceeds-remaining"

The refund scenarios make approval, expiry, and the limit on partial refunds concrete. section 1.5

Use an iterative authoring loop:

  • Prototype to discover the real rules and checks; keep the prototype simple and treat it as disposable. section 1.5
  • Specify observable behavior and boundary cases, then add application constraints such as money representation and idempotency strategy. section 1.5
  • Ask an agent for focused, verifiable artifacts and additional corner cases. Review its proposals against human intent rather than accepting them as the specification. section 1.5 section 1.4.1
  • Keep asking what the contract omits. A generated test suite may appear exhaustive while sharing its author’s blind spots. section 1.4.1

Checking a refund boundary

From the refund scenarios, an agent can be asked to generate Cucumber step definitions, a pure refund policy, and property tests probing 29d23h59m, 30d00m00s, and 30d+ε. The request also calls for a rationale about time zones and rounding. These outputs still need review against the intended policy. section 1.5 section 1.4.1

Even a refined specification can omit real input: an ISBN validation case may account for hyphens but miss spaces. Add the missing case, check the intended standard, and continue looking for unstated assumptions. section 1.4.1

How Vibe Engineering covers it

How deep it goes
Works through prototype discovery, executable scenarios, artifact generation, and review, while emphasizing that specifications and tests remain incomplete.
Examples
Uses refund approval and rejection scenarios, time-boundary probes, and an ISBN validation case involving spaces.
What you can do after
Practice authoring reviewable behavior scenarios and using AI to propose testable artifacts and overlooked cases.
How it connects
Connects executable specifications with prototyping, acceptance testing, property testing, and continuous integration.

Also explained in

Compare how 2 books explain specification authoring →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vibe Engineering. The section links point to the parts of the book it draws on.