Authoring ProductSpec Files

ProductSpec is a Markdown format for the product decision that comes before tickets, engineering plans, and code. One file per feature holds the committed intent.

This skill covers producing that file. Reading a finished spec and building against it is a different job, and the productspec skill covers it. This skill ends when the file validates.

Always true

• Files use the extension .product-spec.md: YAML frontmatter between --- markers, then ## Section headings.
• Six sections are mandatory, in order: problem, hypothesis, productsummary, scope, acceptancecriteria, success_metrics.
• Headings match case- and separator-insensitively. ## Acceptance Criteria and ## acceptance_criteria are the same section. Title case is the convention.
• Frontmatter requires specformatversion: "0.1", title, artifacttype (hypothesis | prd | openspecproposal), author, createdat, updatedat. Optional: specrevision, linkedgithubrepo, appliesto, customsections, toolmetadata.
• acceptancecriteria and successmetrics each carry a required fenced block. Prose alone fails validation. Structured scope, AI evals, and related artifacts are optional.
• Structured items carry durable ids: AC-<number>, SM-<number>, EVAL-<number>. Other documents cite them.
• AI evals live inside ## Acceptance Criteria, never in a section of their own. Related artifacts live inside ## Related Artifacts.
• Validate any file with: npm exec --yes --package @productspec/parser -- productspec validate <file> (--yes suppresses npm's interactive install prompt, which hangs CI and non-interactive agents).
• The full normative definition is SPEC.md in the ProductSpec repository: https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md. When this skill and SPEC.md disagree, SPEC.md wins.

Pick the task, read one reference

Read only the reference the task needs.

Ground rules

• Never renumber a durable id. AC-2 means the same criterion tomorrow as it does today, because a ticket, an engineering spec, or another agent may cite it. Add new ids at the end.
• A success metric needs a target and a window, and the block is required. When the number depends on a baseline that only exists after launch, write target: tbd with targetstatus: provisional and a named targetowner. Never invent a number to clear the validator.
• Preserve the author's Markdown inside sections. Tables, lists, and links survive the format. Do not flatten them.
• Write Scope items as complete sentences or imperative statements. Avoid terse tags like search or storage.
• spec_revision increments only when product intent materially changes, never for typo or formatting edits.