Spec-First Development Hub

Use this hub at the moment a ticket stops being obvious. That usually happens when a feature touches money, data integrity, permissions, API behavior, or a release path that would be painful to unwind. The goal is not to write a large document. The goal is to identify the few decisions that would otherwise be invented during implementation.

A practical sprint workflow is simple: pick one ticket, open the starter block, fill the non-goals first, then write only the acceptance criteria that would change how an engineer designs the solution. If the criteria do not change implementation or testing, they are probably decorative. Cut them and spend the time on failure paths, rollback, and the person who owns the decision.

During review, ask each role for a different kind of objection. Product should reject unclear scope. Engineering should reject hidden dependencies. QA should reject criteria with no fixture or observable result. Operations should reject rollout plans without a stop signal. When every role can reject something specific, the spec is doing work.

• The spec describes the feature but does not decide anything.
• The non-goals are so broad that they cannot stop scope creep.
• Acceptance criteria repeat the happy path and skip duplicate, timeout, permission, or rollback cases.
• Review approval is treated as proof even though no runtime evidence exists.

The handoff artifact should be short enough to live in the ticket but complete enough to survive a new engineer joining mid-sprint. Link the final spec from the issue, PR, and release note so future changes can find the original decision path.

A common example is a refund workflow that starts as a single sentence in a planning ticket. The spec-first pass should not begin by choosing a framework or database shape. It should begin by deciding refund window, idempotency behavior, event emission, support override, audit logging, and rollback when the payment provider times out. Once those decisions are visible, implementation becomes smaller because the team no longer debates policy while reading a diff.

The author should attach one rejected alternative. For the refund example, that might be “allow refunds older than 90 days with manager approval.” Recording why it was rejected protects future reviewers from reopening the same argument. The release note should then link the spec, the acceptance tests, and the metric that shows duplicate refund attempts stayed at zero during rollout.

A refund workflow is useful because it exposes the full spec-first chain: product policy, API behavior, support operations, event delivery, and rollback all meet in one small feature.

Before treating this hub as complete for a real team, run a short audit. First, confirm the reader can leave the page with one artifact copied into their workflow. Second, confirm every linked article answers a different question instead of repeating the same definition. Third, confirm the page names a failure mode that would matter in production, not only during planning.

The most useful hubs behave like workbenches. A reader should be able to open the page, choose the relevant path, copy the block, and know what evidence to attach before review. If a hub only explains the topic, it becomes another article. If it helps the reader decide what to do next, it becomes a resource.