/product — Interactive PRODUCT.md Generation

Purpose: Guide the user through creating a
PRODUCT.md
that unlocks product-aware council reviews in
/pre-mortem
and
/vibe
.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

CLI dependencies: None required.

Execution Steps

Given

/product [target-dir]

```
target-dir
```
defaults to the current working directory.

Step 1: Pre-flight

Check if PRODUCT.md already exists:

bash

ls PRODUCT.md 2>/dev/null

If it exists:

Use AskUserQuestion:

Question: "PRODUCT.md already exists. What would you like to do?"
Options:
- "Overwrite — start fresh" → continue to Step 2
- "Update — keep existing content as defaults" → read existing file, use its values as pre-populated suggestions in Step 3
- "Cancel" → stop, report no changes

If it does not exist: continue to Step 2.

Step 2: Gather Context

Read available project files to pre-populate suggestions:

README.md — extract project description, purpose, target audience
package.json / pyproject.toml / go.mod / Cargo.toml — extract project name
Directory listing —
```
ls
```
the project root for structural hints

Use what you find to draft initial suggestions for each section. If no files exist, proceed with blank suggestions.

Step 3: Interview

Ask the user about each section using AskUserQuestion. For each question, offer pre-populated suggestions from Step 2 where available.

3a: Mission

Ask: "What is your product's mission? (One sentence: what does it do and for whom?)"

Options based on README analysis:

Suggested mission derived from README (if available)
A shorter/punchier variant
"Let me type my own"

3b: Target Personas

Ask: "Who are your primary users? Describe 2-3 personas."

For each persona, gather:

Role (e.g., "Backend Developer", "DevOps Engineer")
Goal — what they're trying to accomplish
Pain point — what makes this hard today

Use AskUserQuestion for the first persona's role, then follow up conversationally for details and additional personas. Stop when the user says they're done or after 3 personas.

3c: Core Value Propositions

Ask: "What makes your product worth using? List 2-4 key value propositions."

Options:

Suggestions derived from README/project context
"Let me type my own"

3d: Competitive Landscape

Ask: "What alternatives exist, and how do you differentiate?"

Gather:

Alternative names
Their strengths
Your differentiation

If the user says "none" or "skip", write "No direct competitors identified" in the section.

Step 4: Generate PRODUCT.md

Write

PRODUCT.md

to the target directory with this structure:

markdown

---
last_reviewed: YYYY-MM-DD
---

# PRODUCT.md

## Mission

{mission from 3a}

## Target Personas

### Persona 1: {role}
- **Goal:** {goal}
- **Pain point:** {pain point}

{repeat for each persona}

## Core Value Propositions

{bullet list from 3c}

## Competitive Landscape

| Alternative | Strength | Our Differentiation |
|-------------|----------|---------------------|
{rows from 3d}

## Usage

This file enables product-aware council reviews:

- **`/pre-mortem`** — Automatically includes `product` perspectives (user-value, adoption-barriers, competitive-position) alongside plan-review judges when this file exists.
- **`/vibe`** — Automatically includes `developer-experience` perspectives (api-clarity, error-experience, discoverability) alongside code-review judges when this file exists.
- **`/council --preset=product`** — Run product review on demand.
- **`/council --preset=developer-experience`** — Run DX review on demand.

Explicit `--preset` overrides from the user skip auto-include (user intent takes precedence).

Set

last_reviewed

to today's date (YYYY-MM-DD format).

Step 5: Report

Tell the user:

What was created:
```
PRODUCT.md
```
at
```
{path}
```
What it unlocks:
- ```
/pre-mortem
```
  will now auto-include product perspectives (user-value, adoption-barriers, competitive-position)
- ```
/vibe
```
  will now auto-include developer-experience perspectives (api-clarity, error-experience, discoverability)
- ```
/council --preset=product
```
  and
```
/council --preset=developer-experience
```
  are available on demand
Next steps: Suggest running
```
/pre-mortem
```
on their next plan to see product perspectives in action

Examples

Creating Product Doc for New Project

User says:

/product

What happens:

Agent checks for existing PRODUCT.md, finds none
Agent reads README.md and package.json to extract project context
Agent asks user about mission, suggesting "CLI tool for automated dependency updates"
Agent interviews for 2 personas: DevOps Engineer and Backend Developer
Agent asks about value props, user provides: "Zero-config automation, Safe updates, Time savings"
Agent asks about competitors, user mentions Renovate and Dependabot
Agent writes PRODUCT.md with all gathered information and today's review date

Result: PRODUCT.md created, unlocking product-aware council perspectives in future validations.

Updating Existing Product Doc