Technical specification from product decisions

Use this workflow to turn a product decision record into a technical specification that engineering can approve, challenge or schedule. It is for engineering leads and product managers who need one buildable account of scope, constraints, open questions and acceptance criteria.

The output is not a promise that the design is correct. It is a review document: it makes the assumptions visible before work starts.

1. Assemble the decision pack

Create one working document called spec-inputs. Put dated source material beneath these headings:

• Problem statement: user, user need, business outcome and why this work is needed now.
• Product decisions: agreed behaviour, priority, scope boundaries and named decision owners.
• Constraints: supported platforms, existing services, security requirements, performance expectations, delivery dependencies and operational limits.
• Open questions: unknown behaviour, missing ownership, undecided trade-offs and external dependencies.
• Evidence: links or pasted extracts from tickets, design notes, customer feedback and prior incident write-ups.
• Known exclusions: work that sounds related but is not part of this build.

Give every item a source label, such as Product review, 14 May or Architecture note, section 3. If two sources conflict, retain both. Do not resolve the conflict by silently choosing the newer-looking wording.

Remove credentials, access tokens, customer identifiers and production secrets before sharing material with the model. Check your organisation's rules for approved data handling first. For current product capabilities and usage details, consult the xAI documentation overview.

2. Separate facts from decisions still needed

Read spec-inputs once before prompting. Create a short issue list with three labels:

Label	Use it for	Result in the specification
Confirmed	A decision with a named source or owner	State it as a requirement or constraint
Assumption	A plausible working interpretation	Mark it for confirmation
Open decision	A choice that changes scope, design or risk	Put it in the decision log

This step stops the model from treating a product discussion as settled engineering direction. It also shows whether you are asking for a specification too early.

For each open decision, record:

• the question to answer;
• the options currently available;
• the impact of delaying the decision;
• the person or team who can decide it;
• the date or planning event by which it is needed.

Do not require the model to invent options where the product team has not described the problem clearly. Ask it to flag the gap instead.

3. Generate the first specification draft

Give the model the assembled material and ask for a structured draft. State that it must distinguish source-backed requirements from assumptions. Use this prompt, replacing the bracketed text:

Create a technical specification for engineering approval from the material below.

Use only the supplied material. Do not invent integrations, metrics, ownership, dates or implementation details. Where information is absent or conflicts, add an item to Open questions or Assumptions.

Write these sections in this order:
1. Problem and intended outcome
2. Scope
3. Out of scope
4. User and system behaviour
5. Technical approach and affected components
6. Requirements and constraints
7. Acceptance criteria
8. Failure modes and operational considerations
9. Dependencies
10. Open questions
11. Decision log
12. Rollout, monitoring and rollback considerations

For every acceptance criterion, use observable language. Include the actor, action, expected result and condition where relevant. Give each criterion an ID such as AC-01.

For every decision-log item, include: decision needed, options, recommendation only if supported by the input, owner, status, and source.

Material:
[PASTE spec-inputs HERE]

Ask for a document that engineers can review in one sitting. If the input is large, split it by source and first ask for a reconciled list of confirmed points, assumptions and conflicts. Then use that list as the input to the specification prompt.

4. Make acceptance criteria testable

Review the generated Acceptance criteria section line by line. Replace vague terms such as “fast”, “secure”, “works correctly” and “handles errors” with behaviour that a reviewer can observe.

Use this pattern:

AC-03: When [actor] performs [action] under [condition], the system [expected result].

For example, do not write “Users can retry failed uploads.” Write the states and result that matter: what makes an upload failed, what action retries it, whether duplication is prevented, and what the user sees after the retry.

Add criteria for the paths that are often omitted:

• invalid or incomplete input;
• duplicate requests;
• dependency failure or timeout;
• permission failure;
• partial completion;
• observable logs, alerts or support signals where the system is operationally important;
• rollback behaviour, if the release changes stored data or externally visible behaviour.

5. Check the draft against the source material

Do not approve a fluent document without comparison. Create a two-column review table in the specification:

Source item	Specification location and status
Product decision	Section and requirement ID, or marked missing
Constraint	Section and constraint ID, or marked missing
Open question	Decision-log ID and owner, or marked missing
Exclusion	Out-of-scope statement, or marked missing

Then run these checks:

1. Search for every number, named system, team name and external dependency. Confirm each appears in spec-inputs or is clearly labelled an assumption.
2. Check that each in-scope behaviour has at least one acceptance criterion.
3. Check that each acceptance criterion belongs to scope. Remove criteria that introduce new work.
4. Check that every open question has an owner and a consequence. “To confirm” is not an owner.
5. Check the rollout and rollback sections against the type of change. If no rollout approach is known, record that as an open decision.

The output is wrong when it appears more certain than the source material, when it adds a component nobody agreed to build, or when a requirement cannot be traced to a decision, constraint or explicit assumption. It is also wrong when it calls a question “open” but gives the team no person to ask.

6. Run the engineering approval review

Send the specification with the decision pack, not by itself. Ask reviewers to comment under one of four headings:

• Incorrect: conflicts with known system behaviour or a source decision.
• Missing: necessary behaviour, dependency, constraint or failure mode is absent.
• Unclear: more than one reasonable interpretation exists.
• Decision needed: engineering approval depends on an unresolved choice.

Hold approval until the document has a named owner, a revision date, resolved blocking decisions, and an explicit list of accepted assumptions. Record rejected alternatives in the decision log when they are likely to be raised again.

Handover the approved specification to the delivery team with the source links, review comments and a list of decisions that must be revisited during design or release planning.

When it does not work

If the draft is generic, the inputs are probably generic. Add the actual user flow, affected systems, constraint wording and examples of unacceptable behaviour, then generate the relevant section again.

If reviewers disagree, do not ask the model to choose a winner. Add the disagreement to the decision log, name the decision owner and state what changes under each option. If the specification keeps expanding, move new requests into Out of scope or create a separate decision record before asking engineering for approval.