Write a Product Spec

Turn an accepted product problem into a clear definition of what should change and how the team will know it works.

Do not hide unresolved product decisions behind a polished template.

1. Confirm the accepted problem

Clarify:

• problem;
• affected users;
• affected situations;
• desired outcome;
• decision owner;
• scope;
• timing;
• constraints;
• why the work is being specified now.

Use approved source-linked context where available:

• customer feedback;
• product evidence;
• metrics;
• current behavior;
• strategy;
• previous decisions.

If customer evidence still requires synthesis, use the customer-feedback workflow first.

Feedback synthesis can inform a problem but does not automatically approve:

• roadmap priority;
• solution.

If the problem or priority is not accepted, produce a smaller decision brief or open-question list instead of inventing a specification.

2. Understand the current product

Inspect relevant:

• current flow;
• product surfaces;
• documentation;
• previous decisions;
• related tickets;
• constraints;
• dependencies;
• analytics;
• meetings;
• repository context

when they change the product definition.

Keep distinct:

• current behavior;
• user evidence;
• stakeholder request;
• product judgment;
• technical constraint.

Expose conflicting evidence and stale assumptions.

3. Define the product change

Build the specification around:

Problem and Evidence

• problem;
• users;
• situations;
• desired outcomes;
• supporting evidence.

Scope

• goals;
• non-goals;
• boundaries.

User Experience

• primary flow;
• alternate flows;
• empty states;
• error states;
• permission states;
• recovery states.

Requirements

• functional requirements;
• relevant experience requirements;
• product rules;
• content/data needs.

Dependencies and Change Management

• dependencies;
• migrations;
• rollout considerations.

Measurement

• success measures;
• guardrails.

Acceptance

• observable acceptance criteria.

Open Decisions

• risks;
• questions;
• owners;
• unresolved choices.

Requirements should describe product behavior and desired outcomes.

Do not disguise implementation choices as product requirements.

Keep separate:

• architecture;
• detailed system design;
• engineering task breakdown;
• code changes.

4. Calibrate uncertain interactions early

When scope or interaction design is uncertain, present first:

• critical user flow;
• highest-risk product choices.

Let the team correct these before expanding the complete specification.

5. Validate the spec

Trace consequential requirements back to:

• accepted problem;
• evidence;
• constraint;
• decision.

Check for:

• contradictory rules;
• missing states;
• hidden dependencies;
• undefined terms;
• untestable criteria;
• unsupported claims;
• accidental scope growth;
• metrics that cannot answer whether the outcome improved.

Ask domain owners only about decisions they genuinely own.

Possible owners include:

• product;
• design;
• engineering;
• data;
• legal;
• support;
• go-to-market.

Record accepted decisions and leave unresolved items visible.

6. Deliver the specification

Provide a concise spec in the team's useful format.

Include:

• short decision summary;
• source links;
• clear acceptance criteria;
• remaining decisions that could change implementation.

Follow active scoped permission for document or product-record actions.

Creating/updating a spec is separate from:

• ticket creation;
• roadmap change;
• architecture;
• implementation;
• release.

If success metrics need definition or current performance needs review, route to product-metrics review.

7. Preserve durable spec conventions

After the format proves useful, preserve:

• terminology;
• spec structure;
• source hierarchy;
• review behavior.

Do not preserve unresolved assumptions as accepted product rules.