/product-spec

Product specification

Move from a product decision to an implementable, testable change. Do not manufacture technical detail before the audience, problem, and scope are credible.

Choose a mode

• Brief: clarify audience, trigger, problem, promise, smallest value path, and exclusions.
• Greenfield buildable spec: define a new v1 and its operating boundary.
• Change spec: fit a feature or behavior change into an existing product and architecture.
• Audit: find contradictions, missing states, untestable requirements, and infeasible scope.
• Solo-MVP modifier: constrain to a short, one-person build only when that is the actual goal.

Do not automatically prepend a brief to an audit or a sufficiently grounded change spec.

Workflow

1. Read research, conversation context, decisions, existing specs, repository, architecture, constraints, and conventions. Ask only blocking questions.
2. Separate facts, observations, assumptions, decisions, and open questions.
3. Define target user or role, triggering situation, current workaround, desired outcome, product promise, and mechanism. Use a real person only when it improves evidence; do not force one where role/context is the correct unit.
4. Draw the boundary: included capabilities, exclusions, dependencies, success signals, and smallest end-to-end path that proves value.
5. Map primary, alternate, and failure flows: first use, empty, loading, offline/timeout, permission, validation, conflict, error, success, cancellation, recovery, and deletion where relevant.
6. For technical work, inspect the existing stack before proposing architecture. Define entities and lifecycle, ownership, authorization, APIs/routes, integrations, background work, idempotency/concurrency, migrations, privacy/security, accessibility, observability, performance/SLOs, and operational needs in proportion to risk.
7. Split delivery into vertical slices that each produce a testable user outcome. Trace each outcome through flow/state, data/API change, acceptance criterion, and verification.
8. Define rollout, compatibility, migration/backfill, kill/rollback, and cleanup when modifying a live system.
9. Record decisions, risks, confidence, unresolved questions, and owners. Never bury uncertainty inside confident requirements.

Load conditional references

• Read product brief only for brief mode or when product framing is genuinely incomplete.
• Read technical specification for greenfield, change-spec, or technical-audit detail.

References provide templates and prompts, not mandatory interviews. This file is authoritative.

Output contract

For a brief, return audience/trigger, problem/evidence, promise/mechanism, smallest value path, scope, exclusions, success signals, assumptions, and open questions.

For a buildable or change spec, add flows/states, architecture fit, data and authorization, interfaces, non-functional requirements, rollout/migration, vertical slices, acceptance criteria, verification, risks, and decisions. For an audit, return findings with evidence, impact, and required correction rather than silently rewriting product intent.

Verify

• Scope traces to a stated user outcome and evidence.
• Facts, assumptions, decisions, and open questions are distinguishable.
• Primary and failure states are covered.
• Data ownership and authorization are explicit.
• Interfaces and acceptance criteria are testable.
• Migration, compatibility, observability, security/privacy, and rollback are addressed proportionally.
• Every delivery slice yields a verifiable user outcome.

Product brief template and prompts

Use this reference only for brief mode or when product framing is incomplete. Do not restart an interview or require answers the available context already contains.

Evidence prompts

Ask at most one blocking question at a time. Useful gaps include:

• Who encounters the problem, in what triggering situation?
• What do they do now, and what evidence shows the workaround is costly or inadequate?
• What changed outcome matters to them?
• What mechanism could plausibly create that outcome?
• What is the smallest end-to-end value path?
• What must explicitly not be included?

A role, team, or account can be the correct user unit. Do not force a named real person when it adds no evidence.

Brief structure

# Product brief: [name]

## Audience and trigger
[Specific user/role/account and the situation that creates the need]

## Problem and evidence
[Current behavior/workaround, cost or failure, evidence, and uncertainty]

## Desired outcome
[Observable change for the user or business]

## Product promise and mechanism
[What the product enables and why the mechanism could work]

## Smallest value path
1. [Trigger or entry]
2. [Core action]
3. [Value realized]

## In scope
- [Capability required for the value path]

## Explicitly out of scope
- [Adjacent capability intentionally excluded and why]

## Success signals
- [Leading behavior]
- [Outcome and measurement window]
- [Guardrail]

## Facts, assumptions, decisions, and open questions
[Four visibly separate lists]

Scope tests

• Does each included capability support the smallest value path?
• Can a removed capability wait without making the path dishonest or unsafe?
• Are authentication, support, billing, compliance, or accessibility requirements being mistaken for optional “features”?
• Does the brief define a learning outcome, not only a shipping deadline?

Do not use arbitrary list lengths. An exclusion list should be long enough to prevent the actual scope risks.

Brief audit

Flag:

• audience defined only by demographics or broad title;
• solution language replacing problem evidence;
• unsupported conversion or market claims;
• a feature list without a value path;
• scope that ignores mandatory operational or safety work;
• success metrics without denominator/window;
• assumptions written as requirements.

Buildable technical specification

Adapt this reference to the existing architecture and selected mode. It is not a default stack recommendation or a mandatory interview.

Contents

• Architecture fit
• Flows and states
• Data and authorization
• Interfaces and background work
• Non-functional requirements
• Delivery and rollout
• Acceptance and verification

Architecture fit

Document the relevant current state before proposing change:

• component/service boundaries and owners;
• frameworks, persistence, auth, queues, analytics, deployment;
• existing conventions and reusable modules;
• known constraints, debt, and incompatible assumptions;
• build-versus-buy decision and reversibility where relevant.

Prefer the smallest change consistent with the product outcome and operating risk. Do not introduce a fashionable stack to a working repository without evidence.

Flows and states

For each user/system flow, specify:

Consider first use, repeat use, empty, loading, validation, permission denied, conflict, timeout, partial failure, cancellation, retry, success, deletion, and support recovery as applicable.

Data and authorization

For each entity:

• purpose and owner/tenant;
• identifiers and relationships;
• lifecycle and allowed state transitions;
• required/optional fields and constraints;
• source of truth and derived fields;
• retention, deletion, export, and audit needs;
• migration/backfill and compatibility;
• authorization matrix by actor and operation.

Address idempotency, unique constraints, concurrency, ordering, and transaction boundaries where multiple writes or retries can occur.

Interfaces and background work

For each API, event, job, or integration, define:

• caller/consumer and authorization;
• input/output schema and versioning;
• validation and stable error contract;
• idempotency/retry/timeout behavior;
• rate and size limits;
• observability and privacy classification;
• dependency failure and recovery;
• compatibility/deprecation policy.

Use concrete endpoints only when the architecture calls for them. UI routes are not a substitute for state and permission requirements.

Non-functional requirements

Include proportional requirements for:

• security and abuse prevention;
• privacy, consent, retention, and deletion;
• accessibility and responsive/input behavior;
• performance budgets and service objectives;
• reliability, backups, and disaster recovery;
• analytics and auditability;
• support and operational ownership;
• cost limits and capacity.

Mark what is required for launch, what can be monitored, and what is explicitly deferred with risk accepted.

Delivery and rollout

Use vertical slices:

user outcome
→ flow and states
→ data/interface changes
→ implementation boundary
→ acceptance criteria
→ verification evidence

For live changes, define feature gating, migration order, backward compatibility, canary population, monitoring, rollback trigger, backout steps, and stale-code/data cleanup.

The solo-MVP modifier may constrain time and staffing, but it does not remove mandatory security, data integrity, or accessibility work.

Acceptance and verification

Write acceptance criteria as observable behavior under explicit conditions. Cover happy path, permission, validation, dependency failure, concurrency/idempotency, accessibility, observability, migration, and rollback as risk requires.

Specify verification method and environment:

• unit/property tests for invariants;
• integration/contract tests for boundaries;
• end-to-end tests for value paths;
• migration rehearsal and reconciliation;
• security/privacy/accessibility checks;
• load/performance tests where thresholds matter;
• deployed smoke tests and telemetry confirmation.