How to turn an idea into a software specification

01 / Scenario

Start with the boundary, not the model.

Suppose a clinic says, “Send appointment reminders from our existing CRM in two weeks.” The request sounds small, but provider choice, consent evidence, retry rules, timezone behavior, cancellations, and duplicate protection all affect the design. The workflow below keeps the useful boundary small without pretending those choices are already settled.

02 / Workflow

A repeatable sequence.

1. 01

   Frame the change in one page

   Name the primary user, trigger, desired outcome, system of record, V1 boundary, and non-goals. If the frame cannot fit on one page, the release is probably carrying more than one product decision.

2. 02

   Build an evidence register

   Classify each important statement as supplied fact, verified evidence, inference, assumption, or unknown. A model can help structure the register, but it cannot promote an assumption into stakeholder approval.

3. 03

   Map the user and system flow

   Write the happy path and the consequential branches: cancellation, invalid data, duplicate jobs, external-provider failure, and daylight-saving transitions. Keep actions and system state changes separate.

4. 04

   Resolve or expose material decisions

   Make the decision, identify an owner and deadline, or mark the item as a blocker. Do not hide unresolved choices inside implementation tasks.

5. 05

   Write requirements and acceptance together

   Each requirement should lead to observable acceptance evidence. For the reminder example, “one reminder per appointment” needs an idempotency scenario, not only a sentence in the spec.

6. 06

   Plan vertical slices

   Sequence work so each slice proves a behavior: scheduling, cancellation, provider failure, visibility, and release controls. Avoid task lists that separate every frontend, backend, and database action from the user outcome.

03 / Fictional worked excerpt

What a bounded output looks like.

The table below condenses a fictional example included for demonstration. It is not a customer result, production test, approval, or performance claim.

04 / Failure modes

Where otherwise plausible AI output goes wrong.

• Starting with architecture before the user and outcome are fixed
• Treating model-generated market or stakeholder statements as evidence
• Writing requirements without failure states or observable acceptance
• Letting unresolved decisions disappear into a generic backlog

05 / Read-only checklist

Use this before calling the artifact complete.

• One primary user and trigger
• System of record and authority boundary
• Explicit V1 and non-goals
• Evidence register with unknowns
• Happy path plus consequential failures
• Decision owner for each blocker
• Acceptance evidence for every material requirement

This checklist is intentionally read-only: it helps you inspect a workflow without exposing the full native skill files, portable prompts, templates, or the bundle-exclusive orchestration skill.