write-product-spec

Name: write-product-spec
Author: warpdotdev

146stars1forks

How to install write-product-spec?

warpdotdev/common-skills/write-product-spec

$npx -y skills add warpdotdev/common-skills --skill write-product-spec

Installs into the current project.

Summary

Write a PRODUCT.md spec for a significant user-facing feature in Warp, focused on detailed behavior and validation. Use when the user asks for a product spec, desired behavior doc, or PRD, wants to define feature behavior before implementation, or when the feature is substantial

Files · 1

View on GitHub

SKILL.md

1	# write-product-spec
2
3	Write a `PRODUCT.md` spec for a significant feature in Warp.
4
5	## Overview
6
7	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).
8
9	"User" is not limited to the end user of the Warp app. It means whoever consumes the surface being designed:
10
11	- For UI / UX features: the human using Warp.
12	- For a data model: the code that reads and writes that model.
13	- For an API, protocol, or library: the callers of that API — other services, client code, plugins, or agents.
14	- For a CLI tool or developer-facing surface: the developer invoking it.
15
16	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.
17
18	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.
19
20	Write specs to `specs/<id>/PRODUCT.md`, where `<id>` is one of:
21
22	- a Linear ticket number (e.g. `specs/APP-1234/PRODUCT.md`)
23	- a GitHub issue id, prefixed with `gh-` (e.g. `specs/gh-4567/PRODUCT.md`)
24	- a short kebab-case feature name (e.g. `specs/vertical-tabs-hover-sidecar/PRODUCT.md`)
25
26	`specs/` should contain only id-named directories as direct children — no engineer-named subdirectories.
27
28	Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or `gh` CLI respectively (and `ask_user_question` if team, labels, or repo are unclear).
29
30	## Before writing
31
32	Gather only the context you need: directory id (Linear ticket, GitHub issue, or feature name), feature summary, target users, key behaviors, edge cases, and how the feature will be validated. Use `ask_user_question` for missing context rather than guessing.
33
34	### Figma mocks
35
36	If the feature has any UI or interaction design, ask the user whether a Figma mock exists before drafting the Behavior section, and include the link in the spec when one is provided. A mock is often the most reliable source of truth for visual states, spacing, and edge-case layouts — not asking can cause the Behavior section to guess at intent the designer already settled.
37
38	- If the user provides a link, include it under a short `## Figma` section (or inline near the top of Behavior) as `Figma: <link>`.
39	- If the user confirms no mock exists, note `Figma: none provided` so the absence is explicit rather than ambiguous.
40	- If the feature is purely backend (data model, API, CLI with no visual surface), skip the question and omit the section.
41
42	Do not silently drop design context; an explicit "none" is preferable to no mention at all on features where design would normally be expected.
43
44	## Structure
45
46	Required sections:
47
48	1. Summary — 1–3 sentences describing the feature and desired outcome.
49	2. Behavior — The meat of the spec. An exhaustive English description of how the feature works, written as numbered, testable invariants. See "The Behavior section" below — this is where the spec earns its length, and everything else should stay thin to avoid duplicating it.
50
51	Optional sections — include only when they add signal beyond the core. Omit the heading entirely if empty; do not write "None" as a placeholder.
52
53	- Problem — Include only when the motivation isn't obvious from Summary.
54	- Goals / Non-goals — Include when scope is ambiguous or has been contested.
55	- Figma — Include with a link when one exists, or an explicit `Figma: none provided` note when design matters but no mock exists. Omit entirely for non-visual features. See "Figma mocks" above.
56	- Open questions — Prefer inline `Open question: …` next to the relevant behavior. Include a dedicated sect

People who liked this also viewed

6 picks

Type

write-product-spec

146stars1forks

View on GitHub

How to install write-product-spec?

warpdotdev/common-skills/write-product-spec

$npx -y skills add warpdotdev/common-skills --skill write-product-spec

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# write-product-spec
2
3	Write a `PRODUCT.md` spec for a significant feature in Warp.
4
5	## Overview
6
7	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).
8
9	"User" is not limited to the end user of the Warp app. It means whoever consumes the surface being designed:
10
11	- For UI / UX features: the human using Warp.
12	- For a data model: the code that reads and writes that model.
13	- For an API, protocol, or library: the callers of that API — other services, client code, plugins, or agents.
14	- For a CLI tool or developer-facing surface: the developer invoking it.
15
16	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.
17
18	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.
19
20	Write specs to `specs/<id>/PRODUCT.md`, where `<id>` is one of:
21
22	- a Linear ticket number (e.g. `specs/APP-1234/PRODUCT.md`)
23	- a GitHub issue id, prefixed with `gh-` (e.g. `specs/gh-4567/PRODUCT.md`)
24	- a short kebab-case feature name (e.g. `specs/vertical-tabs-hover-sidecar/PRODUCT.md`)
25
26	`specs/` should contain only id-named directories as direct children — no engineer-named subdirectories.
27
28	Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or `gh` CLI respectively (and `ask_user_question` if team, labels, or repo are unclear).
29
30	## Before writing
31
32	Gather only the context you need: directory id (Linear ticket, GitHub issue, or feature name), feature summary, target users, key behaviors, edge cases, and how the feature will be validated. Use `ask_user_question` for missing context rather than guessing.
33
34	### Figma mocks
35
36	If the feature has any UI or interaction design, ask the user whether a Figma mock exists before drafting the Behavior section, and include the link in the spec when one is provided. A mock is often the most reliable source of truth for visual states, spacing, and edge-case layouts — not asking can cause the Behavior section to guess at intent the designer already settled.
37
38	- If the user provides a link, include it under a short `## Figma` section (or inline near the top of Behavior) as `Figma: <link>`.
39	- If the user confirms no mock exists, note `Figma: none provided` so the absence is explicit rather than ambiguous.
40	- If the feature is purely backend (data model, API, CLI with no visual surface), skip the question and omit the section.
41
42	Do not silently drop design context; an explicit "none" is preferable to no mention at all on features where design would normally be expected.
43
44	## Structure
45
46	Required sections:
47
48	1. Summary — 1–3 sentences describing the feature and desired outcome.
49	2. Behavior — The meat of the spec. An exhaustive English description of how the feature works, written as numbered, testable invariants. See "The Behavior section" below — this is where the spec earns its length, and everything else should stay thin to avoid duplicating it.
50
51	Optional sections — include only when they add signal beyond the core. Omit the heading entirely if empty; do not write "None" as a placeholder.
52
53	- Problem — Include only when the motivation isn't obvious from Summary.
54	- Goals / Non-goals — Include when scope is ambiguous or has been contested.
55	- Figma — Include with a link when one exists, or an explicit `Figma: none provided` note when design matters but no mock exists. Omit entirely for non-visual features. See "Figma mocks" above.
56	- Open questions — Prefer inline `Open question: …` next to the relevant behavior. Include a dedicated sect

People who liked this also viewed

6 picks

Type