A spec gives Product, Engineering, QA, and the agent a shared target: what changes, what constrains it, and how to verify it.

Six questions to answer

  • Outcome: Who benefits, and how?
  • Scope: What changes now? What waits?
  • Behavior: What happens normally, at boundaries, and on failure?
  • Constraints: Which interfaces, permissions, and limits apply?
  • Unknowns: What needs a decision, and who owns it?
  • Verification: Which checks and human decisions establish acceptance?

Example: “Add CSV export”

An illustrative spec makes the hidden decisions explicit:

  • Export all filtered rows, across pagination.
  • Preserve approved column order and access restrictions.
  • Return column headers for an empty result.
  • Show an actionable error if export fails.
  • Resolve the maximum export size before implementation.

These decisions give review and testing a concrete target.

Keep it alive

Write enough for one useful slice. Build, inspect, revise, and version the spec alongside the change. Passing tests supports acceptance; Product still decides whether the need was met.

Repeated misunderstandings are a reason to examine the spec, context, and checks. This connects refinement to validation in APEL.

Sources