Write Product Spec

Write product spec

Contract

Inputs

• Mode (required): product (default), technical, or requirements.
• Feature identifier or intent (required): for product and requirements, a short kebab-case feature name or ticket or issue number; for technical, a description of the feature, change, or system to specify.
• Feature summary (required for product and requirements): one to three sentences describing what the feature does and the desired outcome.
• Target consumers (optional for product): who consumes the surface. Defaults to the end user.
• Key behaviors and edge cases (optional for product): gather via dialogue; do not guess.
• Codebase context (optional for technical): existing files, modules, or architecture the spec must integrate with.
• Target users (optional for requirements): who the feature serves.
• Constraints (optional for requirements): limits on the feature.
• Related URLs or docs (optional for requirements): sources to cite.
• Priority level (optional for requirements): P0, P1, or P2.

Procedure

1. Select the mode. Ask or infer from the request: product for behavioral invariants, technical for implementation plan, requirements for evidence-backed PRD. Default to product if the request does not name a mode. Done when: the mode is confirmed.
2. Confirm scope. Ask only what is strictly necessary; do not guess.
   • Mode product: confirm the feature identifier, feature summary, target consumers, key behaviors, edge cases, and validation approach.
   • Mode technical: confirm the intent, codebase context, and constraints.
   • Mode requirements: confirm the feature name or description, target users, constraints, related URLs or docs, and priority level. Done when: the required scope for the selected mode is confirmed.
3. Mode requirements: gather supporting evidence. Read local sources when present and non-stale (≤7 days): reports/customer_feedback_summaries/, reports/competitor_changelog_reports/ or reports/feature_research/, reports/git_history_analysis/, reports/weekly_product_briefings/. Note absent or stale sources. Cite every claim in the Problem Statement and Technical Considerations sections; tag unattributed claims [UNCITED]. Done when: available sources are read and stale or missing sources are noted.
4. Draft the artifact structure.
   • Mode product: Summary (required), Behavior (required, numbered invariants), optional Problem, optional Goals/Non-goals, optional Open questions. Do not include Validation, Success criteria, or Testing sections.
   • Mode technical: Objective, Background, Design, Implementation plan, Risks and mitigations, Open questions. No placeholders or TODOs.
   • Mode requirements: TL;DR, Problem Statement, Goals & Success Metrics, Target Users, Scope, Proposed Solution, Technical Considerations, Competitive Context, Open Questions, References. Include a header block with title, author, date, status (Draft), priority. Done when: the section list is decided with required and optional sections.
5. Produce the content.
   • Mode product: write Behavior as numbered, testable invariants from the consumer's perspective. Cover default flow, states, inputs, empty/error/loading/cancellation states, edge cases, keyboard/accessibility, and invariants. Keep framing thin relative to Behavior.
   • Mode technical: write each section. Validate every implementation step against the codebase: confirm referenced paths, types, and interfaces exist or are created by a prior step.
   • Mode requirements: write each section with citations. Derive the feature slug from the feature name (lowercase, hyphenated). Done when: all sections are drafted with concrete content and the mode-specific contract is satisfied.
6. Write the artifact.
   • Mode product: specs/<id>/PRODUCT.md where <id> is the feature identifier.
   • Mode technical: TECH.md in the working directory.
   • Mode requirements: reports/prds/prd_<feature_slug>_YYYY-MM-DD.md. Create the directory if it does not exist. Done when: the file is written to the correct path.
7. Mode requirements: publish the PRD. Present the saved path and a content summary. Obtain explicit confirmation. Stage and commit the PRD file; open a pull request against the default branch. If VCS commands fail, report the error. Inform the user that optional exports to Google Docs, Notion, or Slack are separate steps. Done when: the PR is open or the user stops before the PR.
8. Confirm the output. Present the file path, a one-line summary, and a count (behavior invariants for product, implementation steps for technical, or sections for requirements). Done when: the summary and count are presented.

Failure and recovery

To reverse the side effect, delete the written artifact. In requirements mode, a partial result that produced a file but not a PR leaves the file in place.

Output

• Mode product: specs/<id>/PRODUCT.md with sections in order: Summary, Behavior (numbered invariants), optional Problem, optional Goals/Non-goals, optional Open questions; no Validation, Success criteria, or Testing sections.
• Mode technical: TECH.md with sections in order: Objective, Background, Design, Implementation plan, Risks and mitigations, Open questions; no placeholders or TODOs.
• Mode requirements: reports/prds/prd_<feature_slug>_YYYY-MM-DD.md with sections in order: TL;DR, Problem Statement, Goals & Success Metrics, Target Users, Scope, Proposed Solution, Technical Considerations, Competitive Context, Open Questions, References; plus an open PR against the default branch.