write-product-spec

SKILL.md

write-product-spec

Write a PRODUCT.md spec for a significant feature in Warp.

Overview

The product spec should make the desired behavior unambiguous enough that an agent can implement it correctly and avoid regressions. Describe the feature purely from the user's perspective — what the user sees, does, and experiences, and the invariants that must hold for them. Do not include implementation details (internal types, state layout, module boundaries, data flow, algorithms).

"User" is not limited to the end user of the Warp app. It means whoever consumes the surface being designed:

For UI / UX features: the human using Warp.

For a data model: the code that reads and writes that model.

For an API, protocol, or library: the callers of that API — other services, client code, plugins, or agents.

For a CLI tool or developer-facing surface: the developer invoking it.

The spec should describe behavior from that consumer's perspective: the shape of the surface, the operations they can perform, what they see back, invariants they can rely on, and edge cases they must handle — without prescribing how the surface is implemented underneath.

Implementation details, validation, and test planning live in a companion TECH.md, produced by the write-tech-spec skill. Writing the product spec is usually the first step of a two-step process: once PRODUCT.md is agreed on, invoke write-tech-spec to produce TECH.md for the same feature (or let the user know that's the expected next step). The product spec should be written so the tech spec can be written directly from it.